summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/README.md2
-rw-r--r--doc/api/projects.md17
-rw-r--r--doc/development/doc_styleguide.md231
-rw-r--r--doc/install/installation.md6
-rw-r--r--doc/integration/shibboleth.md4
-rw-r--r--doc/release/patch.md2
-rw-r--r--doc/system_hooks/system_hooks.md6
-rw-r--r--doc/update/8.2-to-8.3.md2
-rw-r--r--doc/update/8.3-to-8.4.md148
-rw-r--r--doc/update/patch_versions.md1
10 files changed, 409 insertions, 10 deletions
diff --git a/doc/README.md b/doc/README.md
index 25fe3abcb9a..7d4f84857e0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -70,6 +70,8 @@
## Contributor documentation
+- [Documentation styleguide](development/doc_styleguide.md) Use this styleguide if you are
+ contributing to documentation.
- [Development](development/README.md) Explains the architecture and the guidelines for shell commands.
- [Legal](legal/README.md) Contributor license agreements.
- [Release](release/README.md) How to make the monthly and security releases.
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 37d74216c1b..241229221db 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -76,7 +76,10 @@ Parameters:
"updated_at": "2013-09-30T13: 46: 02Z"
},
"archived": false,
- "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png"
+ "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
+ "shared_runners_enabled": true,
+ "forks_count": 0,
+ "star_count": 0
},
{
"id": 6,
@@ -129,7 +132,11 @@ Parameters:
}
},
"archived": false,
- "avatar_url": null
+ "avatar_url": null,
+ "shared_runners_enabled": true,
+ "forks_count": 0,
+ "star_count": 0,
+ "runners_token": "b8547b1dc37721d05889db52fa2f02"
}
]
```
@@ -244,7 +251,11 @@ Parameters:
}
},
"archived": false,
- "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png"
+ "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
+ "shared_runners_enabled": true,
+ "forks_count": 0,
+ "star_count": 0,
+ "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b"
}
```
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md
new file mode 100644
index 00000000000..0bd32b78201
--- /dev/null
+++ b/doc/development/doc_styleguide.md
@@ -0,0 +1,231 @@
+# Documentation styleguide
+
+This styleguide recommends best practices to improve documentation and to keep
+it organized and easy to find.
+
+## Naming
+
+- When creating a new document and it has more than one word in its name,
+ make sure to use underscores instead of spaces or dashes (`-`). For example,
+ a proper naming would be `import_projects_from_github.md`. The same rule
+ applies to images.
+
+## Text
+
+- Split up long lines, this makes it much easier to review and edit. Only
+ double line breaks are shown as a full line break in [GitLab markdown][gfm].
+ 80-100 characters is a good line length
+- Make sure that the documentation is added in the correct directory and that
+ there's a link to it somewhere useful
+- Do not duplicate information
+- Be brief and clear
+- Unless there's a logical reason not to, add documents in alphabetical order
+- Write in US English
+- Use [single spaces][] instead of double spaces
+
+## Formatting
+
+- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
+- Use the number one (`1`) for ordered lists
+- Use underscores (`_`) to mark a word or text in italics
+- Use double asterisks (`**`) to mark a word or text in bold
+- When using lists, prefer not to end each item with a period. You can use
+ them if there are multiple sentences, just keep the last sentence without
+ a period
+
+## Headings
+
+- Add only one H1 title in each document, by adding `#` at the beginning of
+ it (when using markdown). For subheadings, use `##`, `###` and so on
+- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
+ links shift too, which eventually leads to dead links. If you think it is
+ compelling to add numbers in headings, make sure to at least discuss it with
+ someone in the Merge Request
+- When introducing a new document, be careful for the headings to be
+ grammatically and syntactically correct. It is advised to mention one or all
+ of the following GitLab members for a review: `@axil`, `@rspeicher`,
+ `@dblessing`, `@ashleys`, `@nearlythere`. This is to ensure that no document
+ with wrong heading is going live without an audit, thus preventing dead links
+ and redirection issues when corrected
+- Leave exactly one newline after a heading
+
+## Links
+
+- If a link makes the paragraph to span across multiple lines, do not use
+ the regular Markdown approach: `[Text](https://example.com)`. Instead use
+ `[Text][identifier]` and at the very bottom of the document add:
+ `[identifier]: https://example.com`. This is another way to create Markdown
+ links which keeps the document clear and concise. Bonus points if you also
+ add an alternative text: `[identifier]: https://example.com "Alternative text"`
+ that appears when hovering your mouse on a link
+
+## Images
+
+- Place images in a separate directory named `img/` in the same directory where
+ the `.md` document that you're working on is located. Always prepend their
+ names with the name of the document that they will be included in. For
+ example, if there is a document called `twitter.md`, then a valid image name
+ could be `twitter_login_screen.png`.
+- Images should have a specific, non-generic name that will differentiate them.
+- Keep all file names in lower case.
+- Consider using PNG images instead of JPEG.
+
+Inside the document:
+
+- The Markdown way of using an image inside a document is:
+ `![Proper description what the image is about](img/document_image_title.png)`
+- Always use a proper description for what the image is about. That way, when a
+ browser fails to show the image, this text will be used as an alternative
+ description
+- If there are consecutive images with little text between them, always add
+ three dashes (`---`) between the image and the text to create a horizontal
+ line for better clarity
+- If a heading is placed right after an image, always add three dashes (`---`)
+ between the image and the heading
+
+## Notes
+
+- Notes should be in italics with the word `Note:` being bold. Use this form:
+ `_**Note:** This is something to note._`. If the note spans across multiple
+ lines it's OK to split the line.
+
+## New features
+
+- Every piece of documentation that comes with a new feature should declare the
+ GitLab version that feature got introduced. Right below the heading add a
+ note: `_**Note:** This feature was introduced in GitLab 8.3_`
+- If possible every feature should have a link to the MR that introduced it.
+ The above note would be then transformed to:
+ `_**Note:** This feature was [introduced][ce-1242] in GitLab 8.3_`, where
+ the [link identifier](#links) is named after the repository (CE) and the MR
+ number
+- If the feature is only in GitLab EE, don't forget to mention it, like:
+ `_**Note:** This feature was introduced in GitLab EE 8.3_`. Otherwise, leave
+ this mention out
+
+## API
+
+Here is a list of must-have items. Use them in the exact order that appears
+on this document. Further explanation is given below.
+
+- Every method must have the REST API request. For example:
+
+ ```
+ GET /projects/:id/repository/branches
+ ```
+
+- Every method must have a detailed
+ [description of the parameters](#method-description).
+- Every method must have a cURL example.
+- Every method must have a response body (in JSON format).
+
+### Method description
+
+Use the following table headers to describe the methods. Attributes should
+always be in code blocks using backticks (`).
+
+```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+```
+
+Rendered example:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `user` | string | yes | The GitLab username |
+
+### cURL commands
+
+- Use `https://gitlab.example.com/api/v3/` as an endpoint.
+- Wherever needed use this private token: `9koXpg98eAheJpvBs5tK`.
+- Always put the request first. `GET` is the default so you don't have to
+ include it.
+- Use double quotes to the URL when it includes additional parameters.
+- Prefer to use examples using the private token and don't pass data of
+ username and password.
+
+| Methods | Description |
+| ------- | ----------- |
+| `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed |
+| `-X POST` | Use this method when creating new objects |
+| `-X PUT` | Use this method when updating existing objects |
+| `-X DELETE` | Use this method when removing existing objects |
+
+### cURL Examples
+
+Below is a set of [cURL][] examples that you can use in the API documentation.
+
+#### Simple cURL command
+
+Get the details of a group:
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/gitlab-org
+```
+
+#### cURL example with parameters passed in the URL
+
+Create a new project under the authenticated user's namespace:
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects?name=foo"
+```
+
+#### Post data using cURL's --data
+
+Instead of using `-X POST` and appending the parameters to the URI, you can use
+cURL's `--data` option. The example below will create a new project `foo` under
+the authenticated user's namespace.
+
+```bash
+curl --data "name=foo" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects"
+```
+
+#### Post data using JSON content
+
+_**Note:** In this example we create a new group. Watch carefully the single
+and double quotes._
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v3/groups
+```
+
+#### Post data using form-data
+
+Instead of using JSON or urlencode you can use multipart/form-data which
+properly handles data encoding:
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "title=ssh-key" -F "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v3/users/25/keys
+```
+
+The above example is run by and administrator and will add an SSH public key
+titled ssh-key to user's account which has an id of 25.
+
+#### Escape special characters
+
+Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
+to escape them when possible. In the example below we create a new issue which
+contains spaces in its title. Observe how spaces are escaped using the `%20`
+ASCII code.
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/42/issues?title=Hello%20Dude"
+```
+
+Use `%2F` for slashes (`/`).
+
+#### Pass arrays to API calls
+
+The GitLab API sometimes accepts arrays of strings or integers. For example, to
+restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
+`example.net`, you would do something like this:
+
+```bash
+curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -d "restricted_signup_domains[]=*.example.com" -d "restricted_signup_domains[]=example.net" https://gitlab.example.com/api/v3/application/settings
+```
+
+[cURL]: http://curl.haxx.se/ "cURL website"
+[single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
+[gfm]: http://doc.gitlab.com/ce/markdown/markdown.html#newlines "GitLab flavored markdown documentation"
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 8c4e092c636..e645445df2a 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -231,9 +231,9 @@ sudo usermod -aG redis git
### Clone the Source
# Clone GitLab repository
- sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-3-stable gitlab
+ sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-4-stable gitlab
-**Note:** You can change `8-3-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server!
+**Note:** You can change `8-4-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server!
### Configure It
@@ -348,7 +348,7 @@ GitLab Shell is an SSH access and repository management software developed speci
cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-workhorse.git
cd gitlab-workhorse
- sudo -u git -H git checkout 0.5.3
+ sudo -u git -H git checkout 0.5.4
sudo -u git -H make
### Initialize Database and Activate Advanced Features
diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md
index 6258e5f1030..a0be3dd4e5c 100644
--- a/doc/integration/shibboleth.md
+++ b/doc/integration/shibboleth.md
@@ -1,8 +1,8 @@
# Shibboleth OmniAuth Provider
-This documentation is for enabling shibboleth with gitlab-omnibus package.
+This documentation is for enabling shibboleth with omnibus-gitlab package.
-In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in gitlab-omnibus package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider.
+In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider.
To enable the Shibboleth OmniAuth provider you must:
diff --git a/doc/release/patch.md b/doc/release/patch.md
index 3022e375aca..1c921439156 100644
--- a/doc/release/patch.md
+++ b/doc/release/patch.md
@@ -24,7 +24,7 @@ Use the following template:
- Picked into respective `stable` branches:
- [ ] Merge `x-y-stable` into `x-y-stable-ee`
- [ ] release-tools: `x.y.z`
-- gitlab-omnibus
+- omnibus-gitlab
- [ ] `x.y.z+ee.0`
- [ ] `x.y.z+ce.0`
- [ ] Deploy
diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md
index 49f98ded046..612376e3a49 100644
--- a/doc/system_hooks/system_hooks.md
+++ b/doc/system_hooks/system_hooks.md
@@ -96,6 +96,7 @@ X-Gitlab-Event: System Hook
"project_path_with_namespace": "jsmith/storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
+ "user_username": "johnsmith",
"user_id": 41,
"project_visibility": "private",
}
@@ -115,6 +116,7 @@ X-Gitlab-Event: System Hook
"project_path_with_namespace": "jsmith/storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
+ "user_username": "johnsmith",
"user_id": 41,
"project_visibility": "private",
}
@@ -129,6 +131,7 @@ X-Gitlab-Event: System Hook
"email": "js@gitlabhq.com",
"event_name": "user_create",
"name": "John Smith",
+ "username": "js",
"user_id": 41
}
```
@@ -142,6 +145,7 @@ X-Gitlab-Event: System Hook
"email": "js@gitlabhq.com",
"event_name": "user_destroy",
"name": "John Smith",
+ "username": "js",
"user_id": 41
}
```
@@ -215,6 +219,7 @@ X-Gitlab-Event: System Hook
"group_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
+ "user_username": "johnsmith",
"user_id": 41
}
```
@@ -231,6 +236,7 @@ X-Gitlab-Event: System Hook
"group_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
+ "user_username": "johnsmith",
"user_id": 41
}
```
diff --git a/doc/update/8.2-to-8.3.md b/doc/update/8.2-to-8.3.md
index a3950df5fef..2ca4e1f3770 100644
--- a/doc/update/8.2-to-8.3.md
+++ b/doc/update/8.2-to-8.3.md
@@ -78,7 +78,7 @@ which should already be on your system from GitLab 8.1.
```bash
cd /home/git/gitlab-workhorse
sudo -u git -H git fetch --all
-sudo -u git -H git checkout 0.5.3
+sudo -u git -H git checkout 0.5.4
sudo -u git -H make
```
diff --git a/doc/update/8.3-to-8.4.md b/doc/update/8.3-to-8.4.md
new file mode 100644
index 00000000000..1cbeab3eca3
--- /dev/null
+++ b/doc/update/8.3-to-8.4.md
@@ -0,0 +1,148 @@
+# From 8.3 to 8.4
+
+### 1. Stop server
+
+ sudo service gitlab stop
+
+### 2. Backup
+
+```bash
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
+```
+
+### 3. Get latest code
+
+```bash
+sudo -u git -H git fetch --all
+sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically
+```
+
+For GitLab Community Edition:
+
+```bash
+sudo -u git -H git checkout 8-4-stable
+```
+
+OR
+
+For GitLab Enterprise Edition:
+
+```bash
+sudo -u git -H git checkout 8-4-stable-ee
+```
+
+### 4. Update gitlab-shell
+
+```bash
+cd /home/git/gitlab-shell
+sudo -u git -H git fetch --all
+sudo -u git -H git checkout v2.6.9
+```
+
+### 5. Update gitlab-workhorse
+
+Install and compile gitlab-workhorse. This requires [Go 1.5](https://golang.org/dl)
+which should already be on your system from GitLab 8.1.
+
+```bash
+cd /home/git/gitlab-workhorse
+sudo -u git -H git fetch --all
+sudo -u git -H git checkout 0.5.4
+sudo -u git -H make
+```
+
+### 6. Install libs, migrations, etc.
+
+```bash
+cd /home/git/gitlab
+
+# MySQL installations (note: the line below states '--without postgres')
+sudo -u git -H bundle install --without postgres development test --deployment
+
+# PostgreSQL installations (note: the line below states '--without mysql')
+sudo -u git -H bundle install --without mysql development test --deployment
+
+# Run database migrations
+sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
+
+# Clean up assets and cache
+sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production
+
+```
+
+### 7. Update configuration files
+
+#### New configuration options for `gitlab.yml`
+
+There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`:
+
+```sh
+git diff origin/8-3-stable:config/gitlab.yml.example origin/8-4-stable:config/gitlab.yml.example
+```
+
+#### Nginx configuration
+
+GitLab 8.3 introduced major changes in the NGINX configuration. Ensure you're
+still up-to-date with the latest changes:
+
+```sh
+# For HTTPS configurations
+git diff origin/8-3-stable:lib/support/nginx/gitlab-ssl origin/8-4-stable:lib/support/nginx/gitlab-ssl
+
+# For HTTP configurations
+git diff origin/8-3-stable:lib/support/nginx/gitlab origin/8-4-stable:lib/support/nginx/gitlab
+```
+
+If you are using Apache instead of NGINX please see the updated [Apache templates].
+Also note that because Apache does not support upstreams behind Unix sockets you
+will need to let gitlab-workhorse listen on a TCP port. You can do this
+via [/etc/default/gitlab].
+
+[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache
+[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/lib/support/init.d/gitlab.default.example#L34
+
+#### Init script
+
+We updated the init script for GitLab in order to pass new
+configuration options to gitlab-workhorse. We let gitlab-workhorse
+connect to the Rails application via a Unix domain socket and we tell
+it where the 'public' directory of GitLab is.
+
+```
+cd /home/git/gitlab
+sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
+```
+
+### 8. Start application
+
+ sudo service gitlab start
+ sudo service nginx restart
+
+### 9. Check application status
+
+Check if GitLab and its environment are configured correctly:
+
+ sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
+
+To make sure you didn't miss anything run a more thorough check:
+
+ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
+
+If all items are green, then congratulations, the upgrade is complete!
+
+## Things went south? Revert to previous version (8.3)
+
+### 1. Revert the code to the previous version
+
+Follow the [upgrade guide from 8.2 to 8.3](8.2-to-8.3.md), except for the
+database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
+
+```bash
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
+```
+
+If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above.
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index c19ee49f9e0..a10e62877ba 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -48,6 +48,7 @@ sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -b v`ca
cd /home/git/gitlab-workhorse
sudo -u git -H git fetch
sudo -u git -H git checkout `cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` -b `cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION`
+sudo -u git -H make
```
### 5. Install libs, migrations, etc.
View Lorry Controller Status