From 0134a85bee1e1f932d7c9d8752d8eb8e5148baf2 Mon Sep 17 00:00:00 2001 From: Christian Mehlmauer Date: Mon, 4 Jan 2016 00:29:30 +0100 Subject: added make command to docs --- doc/update/patch_versions.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') 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. -- cgit v1.2.1 From ba9799b42f5bc861df1fc5d41c149cf72e9daf04 Mon Sep 17 00:00:00 2001 From: Tomasz Maczukin Date: Thu, 7 Jan 2016 10:39:02 +0100 Subject: Update ./doc/api --- doc/api/projects.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/api/projects.md b/doc/api/projects.md index 0ca81ffd49e..96a3f08490c 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -76,7 +76,14 @@ 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, + "build_allow_git_fetch": true, + "build_coverage_regex": null, + "build_timeout": 3600, + "runners_token": "4f9e77be0eed5ef29548fccda3b371" }, { "id": 6, @@ -129,7 +136,14 @@ Parameters: } }, "archived": false, - "avatar_url": null + "avatar_url": null, + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "build_allow_git_fetch": true, + "build_coverage_regex": null, + "build_timeout": 3600, + "runners_token": "b8547b1dc37721d05889db52fa2f02" } ] ``` @@ -244,7 +258,14 @@ 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, + "build_allow_git_fetch": true, + "build_coverage_regex": null, + "build_timeout": 3600, + "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b" } ``` @@ -409,6 +430,9 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) +- `build_allow_git_fetch` (optional) +- `build_timeout` (optional) +- `build_coverage_regex` (optional) ### Create project for user @@ -431,6 +455,9 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) +- `build_allow_git_fetch` (optional) +- `build_timeout` (optional) +- `build_coverage_regex` (optional) ### Edit project @@ -454,6 +481,9 @@ Parameters: - `snippets_enabled` (optional) - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) +- `build_allow_git_fetch` (optional) +- `build_timeout` (optional) +- `build_coverage_regex` (optional) On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. -- cgit v1.2.1 From dada25d4472ec9ad601447fdd12da2301ac9ee79 Mon Sep 17 00:00:00 2001 From: Tommy Beadle Date: Thu, 7 Jan 2016 12:54:35 -0500 Subject: Include the username in user_create/destroy system hooks. --- doc/system_hooks/system_hooks.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 49f98ded046..0539f30e802 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -129,6 +129,7 @@ X-Gitlab-Event: System Hook "email": "js@gitlabhq.com", "event_name": "user_create", "name": "John Smith", + "username": "js", "user_id": 41 } ``` @@ -142,6 +143,7 @@ X-Gitlab-Event: System Hook "email": "js@gitlabhq.com", "event_name": "user_destroy", "name": "John Smith", + "username": "js", "user_id": 41 } ``` -- cgit v1.2.1 From 1f64332e11949a5954b1e4ac7c6667b03ea70a0b Mon Sep 17 00:00:00 2001 From: Tommy Beadle Date: Thu, 7 Jan 2016 12:54:54 -0500 Subject: Include user_username in user_(add_to/remove_from)_(project/group) system hooks. --- doc/system_hooks/system_hooks.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc') diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 0539f30e802..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", } @@ -217,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 } ``` @@ -233,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 } ``` -- cgit v1.2.1 From fc4108b38b5d0a7fc755c1977663f516b5dea0bd Mon Sep 17 00:00:00 2001 From: Tomasz Maczukin Date: Mon, 11 Jan 2016 15:27:20 +0100 Subject: Modify CI features in projects API --- doc/api/projects.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/api/projects.md b/doc/api/projects.md index 96a3f08490c..4632554bf86 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -79,11 +79,7 @@ Parameters: "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", "shared_runners_enabled": true, "forks_count": 0, - "star_count": 0, - "build_allow_git_fetch": true, - "build_coverage_regex": null, - "build_timeout": 3600, - "runners_token": "4f9e77be0eed5ef29548fccda3b371" + "star_count": 0 }, { "id": 6, @@ -140,9 +136,6 @@ Parameters: "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, - "build_allow_git_fetch": true, - "build_coverage_regex": null, - "build_timeout": 3600, "runners_token": "b8547b1dc37721d05889db52fa2f02" } ] @@ -262,9 +255,6 @@ Parameters: "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, - "build_allow_git_fetch": true, - "build_coverage_regex": null, - "build_timeout": 3600, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b" } ``` @@ -430,9 +420,6 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) -- `build_allow_git_fetch` (optional) -- `build_timeout` (optional) -- `build_coverage_regex` (optional) ### Create project for user @@ -455,9 +442,6 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) -- `build_allow_git_fetch` (optional) -- `build_timeout` (optional) -- `build_coverage_regex` (optional) ### Edit project @@ -481,9 +465,6 @@ Parameters: - `snippets_enabled` (optional) - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) -- `build_allow_git_fetch` (optional) -- `build_timeout` (optional) -- `build_coverage_regex` (optional) On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. -- cgit v1.2.1 From d0b2d278f4fc7c929bd19ce9f29eb689783f58ed Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 12 Jan 2016 11:47:08 +0100 Subject: Move doc_styleguide in the development directory [ci skip] --- doc/README.md | 2 + doc/development/doc_styleguide.md | 224 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 doc/development/doc_styleguide.md (limited to 'doc') 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/development/doc_styleguide.md b/doc/development/doc_styleguide.md new file mode 100644 index 00000000000..df2507a34d0 --- /dev/null +++ b/doc/development/doc_styleguide.md @@ -0,0 +1,224 @@ +# Documentation styleguide + +This styleguide recommends best practices to improve documentation and to keep +it organized and easy to find. + +## Naming + +- Use underscores for all names, including new documentation and 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. + 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 +- Whenever it applies, 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 +- For subtitles, make sure to start with the largest and go down, meaning: + `#` for the title, `##` for subtitles and `###` for subtitles of the subtitles, etc. +- Avoid putting numbers in Markdown headings. Numbers shift hence documentation + anchor links shift too which eventually leads to dead links. +- When introducing a new doc, 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 the link sets the paragraph spanning 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 make Markdown + links which keeps the document clear and concise. Extra 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 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 CE 8.3_` +- If possible every feature should have a link to the MR that introduced it. + The above note would be transformed to: + `_**Note:** This feature was [introduced][ce-1242] in GitLab CE 8.3_`, where + the link is named after the repository (CE) and the MR number, and the + [link identifier](#links) is used. + +## API + +Here is a list of must have items. Use them in this 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. Watch 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 -- cgit v1.2.1 From fac252c9a2230b58b0de7b16fb7318fc048f32a0 Mon Sep 17 00:00:00 2001 From: Jacob Vosmaer Date: Tue, 12 Jan 2016 14:47:55 +0100 Subject: Never heard of gitlab-omnibus --- doc/integration/shibboleth.md | 4 ++-- doc/release/patch.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') 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 -- cgit v1.2.1 From 0e769d2a48032815a8a2a32caae9025f01f92ff4 Mon Sep 17 00:00:00 2001 From: Jacob Vosmaer Date: Tue, 12 Jan 2016 15:18:17 +0100 Subject: Use gitlab-workhorse 0.5.4 Fixes routing errors for /api/v3/projects/ --- doc/install/installation.md | 2 +- doc/update/8.2-to-8.3.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/install/installation.md b/doc/install/installation.md index 8c4e092c636..50ccaabd839 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -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/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 ``` -- cgit v1.2.1 From 20c327fcfde414bbc3011ba076538bfb3d557e94 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 12 Jan 2016 16:16:29 +0100 Subject: Clarify the naming guideline [ci skip] --- doc/development/doc_styleguide.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index df2507a34d0..17c6b9d4c92 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -5,7 +5,10 @@ it organized and easy to find. ## Naming -- Use underscores for all names, including new documentation and images +- 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 -- cgit v1.2.1 From 3dfb69a59f94754320d25b115031766ffc67fcdf Mon Sep 17 00:00:00 2001 From: Robert Speicher Date: Tue, 12 Jan 2016 18:04:02 -0500 Subject: Prepare Installation and Update docs for 8.4 RC1 [ci skip] --- doc/install/installation.md | 4 +- doc/update/8.3-to-8.4.md | 148 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 doc/update/8.3-to-8.4.md (limited to 'doc') diff --git a/doc/install/installation.md b/doc/install/installation.md index 50ccaabd839..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 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. -- cgit v1.2.1 From 4eae95c03c14aefc453cc55f9880056ff06cc684 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 13 Jan 2016 18:24:08 +0100 Subject: Update doc_styleguide.md [ci skip] - Fix some syntax/grammar typos - Link to GFM documentation on newlines - Be less strict on the alphabetical order styleguide - You can override the "numbers in headings" rule if you discuss it first - Do not mention CE in notes if the feature is in both CE and EE --- doc/development/doc_styleguide.md | 52 +++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 24 deletions(-) (limited to 'doc') diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 17c6b9d4c92..0bd32b78201 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -13,13 +13,13 @@ it organized and easy to find. ## 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. + 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 -- Whenever it applies, add documents in alphabetical order +- Unless there's a logical reason not to, add documents in alphabetical order - Write in US English - Use [single spaces][] instead of double spaces @@ -37,27 +37,27 @@ it organized and easy to find. - Add only one H1 title in each document, by adding `#` at the beginning of it (when using markdown). For subheadings, use `##`, `###` and so on -- For subtitles, make sure to start with the largest and go down, meaning: - `#` for the title, `##` for subtitles and `###` for subtitles of the subtitles, etc. -- Avoid putting numbers in Markdown headings. Numbers shift hence documentation - anchor links shift too which eventually leads to dead links. -- When introducing a new doc, 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. +- 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 the link sets the paragraph spanning across multiple lines, do not use +- 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 make Markdown - links which keeps the document clear and concise. Extra points if you also + `[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. + that appears when hovering your mouse on a link ## Images @@ -74,7 +74,7 @@ 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 what the image is about. That way, when a +- 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 @@ -93,16 +93,19 @@ Inside the document: - 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 CE 8.3_` + 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 transformed to: - `_**Note:** This feature was [introduced][ce-1242] in GitLab CE 8.3_`, where - the link is named after the repository (CE) and the MR number, and the - [link identifier](#links) is used. + 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 this exact order that appears +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: @@ -204,7 +207,7 @@ titled ssh-key to user's account which has an id of 25. 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. Watch how spaces are escaped using the `%20` +contains spaces in its title. Observe how spaces are escaped using the `%20` ASCII code. ```bash @@ -225,3 +228,4 @@ curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -d "restricted_signup_domai [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" -- cgit v1.2.1