diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 54 | ||||
| -rw-r--r-- | doc/administration/gitaly/index.md | 24 | ||||
| -rw-r--r-- | doc/administration/plugins.md | 66 | ||||
| -rw-r--r-- | doc/api/commits.md | 3 | ||||
| -rw-r--r-- | doc/api/merge_requests.md | 4 | ||||
| -rw-r--r-- | doc/api/projects.md | 5 | ||||
| -rw-r--r-- | doc/api/services.md | 1 | ||||
| -rw-r--r-- | doc/ci/variables/README.md | 3 | ||||
| -rw-r--r-- | doc/development/ee_features.md | 39 | ||||
| -rw-r--r-- | doc/development/fe_guide/performance.md | 12 | ||||
| -rw-r--r-- | doc/development/fe_guide/vue.md | 10 | ||||
| -rw-r--r-- | doc/development/i18n/externalization.md | 221 | ||||
| -rw-r--r-- | doc/development/i18n/proofreader.md | 1 | ||||
| -rw-r--r-- | doc/development/i18n/translation.md | 45 | ||||
| -rw-r--r-- | doc/install/installation.md | 6 | ||||
| -rw-r--r-- | doc/integration/saml.md | 3 | ||||
| -rw-r--r-- | doc/user/markdown.md | 8 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/index.md | 2 |
18 files changed, 366 insertions, 141 deletions
diff --git a/doc/README.md b/doc/README.md index 46fcb7c6baf..fb7a23e2750 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,4 @@ --- -toc: false comments: false --- @@ -8,15 +7,9 @@ comments: false Welcome to [GitLab](https://about.gitlab.com/), a Git-based fully featured platform for software development! -GitLab offers the most scalable Git-based fully integrated platform for software development, with flexible products and subscription plans. - -With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/products/): Libre, Starter, Premium, and Ultimate. - -Every feature available in Libre is also available in Starter, Premium, and Ultimate. -Starter features are also available in Premium and Ultimate, and Premium features are also -available in Ultimate. - -GitLab.com is our SaaS offering. It's hosted, managed, and administered by GitLab, with [free and paid plans](https://about.gitlab.com/gitlab-com/) for individuals and teams: Free, Bronze, Silver, and Gold. +GitLab offers the most scalable Git-based fully integrated platform for +software development, with flexible products and subscriptions. +To understand what features you have access to, check the [GitLab subscriptions](#gitlab-subscriptions) below. ## Shortcuts to GitLab's most visited docs @@ -124,8 +117,6 @@ Manage your [repositories](user/project/repository/index.md) from the UI (user i - [GitLab Integration](integration/README.md): Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. - [Trello Power-Up](integration/trello_power_up.md): Integrate with GitLab's Trello Power-Up ----- - ## Administrator documentation [Administration documentation](administration/index.md) applies to admin users of GitLab @@ -143,3 +134,42 @@ Learn how to contribute to GitLab: - [Development](development/README.md): All styleguides and explanations how to contribute. - [Legal](legal/README.md): Contributor license agreements. - [Writing documentation](development/writing_documentation.md): Contributing to GitLab Docs. + +## GitLab subscriptions + +You have two options to use GitLab: + +- GitLab self-hosted: Install, administer, and maintain your own GitLab instance. +- GitLab.com: GitLab's SaaS offering. You don't need to install anything to use GitLab.com, +you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab +straight away. + +### GitLab self-hosted + +With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/products/): Libre, Starter, Premium, and Ultimate. + +Every feature available in Libre is also available in Starter, Premium, and Ultimate. +Starter features are also available in Premium and Ultimate, and Premium features are also +available in Ultimate. + +### GitLab.com + +GitLab.com is hosted, managed, and administered by GitLab, Inc., with +[free and paid subscriptions](https://about.gitlab.com/gitlab-com/) for individuals +and teams: Free, Bronze, Silver, and Gold. + +GitLab.com subscriptions grants access +to the same features available in GitLab self-hosted, **expect +[administration](administration/index.md) tools and settings**: + +- GitLab.com Free includes the same features available in GitLab Libre +- GitLab.com Bronze includes the same features available in GitLab Starter +- GitLab.com Silver includes the same features available in GitLab Premium +- GitLab.com Gold includes the same features available in GitLab Ultimate + +For supporting the open source community and encouraging the development of +open source projects, GitLab grants access to **Gold** features +for all GitLab.com **public** projects, regardless of the subscription. + +To know more about GitLab subscriptions and licensing, please refer to the +[GitLab Product Marketing Handbook](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index e3b10119090..d9a61aea6ef 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -2,7 +2,9 @@ [Gitaly](https://gitlab.com/gitlab-org/gitaly) (introduced in GitLab 9.0) is a service that provides high-level RPC access to Git -repositories. Gitaly is a mandatory component in GitLab 9.4 and newer. +repositories. Gitaly was optional when it was first introduced in +GitLab, but since GitLab 9.4 it is a mandatory component of the +application. GitLab components that access Git repositories (gitlab-rails, gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do @@ -184,14 +186,20 @@ Gitaly logs on your Gitaly server (`sudo gitlab-ctl tail gitaly` or coming in. One sure way to trigger a Gitaly request is to clone a repository from your GitLab server over HTTP. -## Disabling or enabling the Gitaly service +## Disabling or enabling the Gitaly service in a cluster environment If you are running Gitaly [as a remote service](#running-gitaly-on-its-own-server) you may want to disable the local Gitaly service that runs on your Gitlab server by default. -To disable the Gitaly service in your Omnibus installation, add the -following line to `/etc/gitlab/gitlab.rb`: +> 'Disabling Gitaly' only makes sense when you run GitLab in a custom +cluster configuration, where different services run on different +machines. Disabling Gitaly on all machines in the cluster is not a +valid configuration. + +If you are setting up a GitLab cluster where Gitaly does not need to +run on all machines, you can disable the Gitaly service in your +Omnibus installation, add the following line to `/etc/gitlab/gitlab.rb`: ```ruby gitaly['enable'] = false @@ -200,11 +208,13 @@ gitaly['enable'] = false When you run `gitlab-ctl reconfigure` the Gitaly service will be disabled. -To disable the Gitaly service in an installation from source, add the -following to `/etc/default/gitlab`: +To disable the Gitaly service in a GitLab cluster where you installed +GitLab from source, add the following to `/etc/default/gitlab` on the +machine where you want to disable Gitaly. ```shell gitaly_enabled=false ``` -When you run `service gitlab restart` Gitaly will be disabled. +When you run `service gitlab restart` Gitaly will be disabled on this +particular machine. diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md new file mode 100644 index 00000000000..c91ac3012b9 --- /dev/null +++ b/doc/administration/plugins.md @@ -0,0 +1,66 @@ +# Plugins + +**Note:** Plugins must be configured on the filesystem of the GitLab +server. Only GitLab server administrators will be able to complete these tasks. +Please explore [system hooks] or [webhooks] as an option if you do not +have filesystem access. + +Introduced in GitLab 10.6. + +A plugin will run on each event so it's up to you to filter events or projects within a plugin code. You can have as many plugins as you want. Each plugin will be triggered by GitLab asynchronously in case of an event. For a list of events please see [system hooks] documentation. + +## Setup + +Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. +There is an `example` directory inside `plugins` where you can find some basic examples. + +Follow the steps below to set up a custom hook: + +1. On the GitLab server, navigate to the project's plugin directory. + For an installation from source the path is usually + `/home/git/gitlab/plugins/`. For Omnibus installs the path is + usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`. +1. Inside the `plugins` directory, create a file with a name of your choice, but without spaces or special characters. +1. Make the hook file executable and make sure it's owned by the git user. +1. Write the code to make the plugin function as expected. Plugin can be + in any language. Ensure the 'shebang' at the top properly reflects the language + type. For example, if the script is in Ruby the shebang will probably be + `#!/usr/bin/env ruby`. +1. The data to the plugin will be provided as JSON on STDIN. It will be exactly same as one for [system hooks] + +That's it! Assuming the plugin code is properly implemented the hook will fire +as appropriate. Plugins file list is updated for each event. There is no need to restart GitLab to apply a new plugin. + +If a plugin executes with non-zero exit code or GitLab fails to execute it, a +message will be logged to `plugin.log`. + +## Validation + +Writing own plugin can be tricky and its easier if you can check it without altering the system. +We provided a rake task you can use with staging environment to test your plugin before using it in production. +The rake task will use a sample data and execute each of plugins. By output you should be able to determine if +system sees your plugin and if it was executed without errors. + +```bash +# Omnibus installations +sudo gitlab-rake plugins:validate + +# Installations from source +bundle exec rake plugins:validate RAILS_ENV=production +``` + +Example of output can be next: + +``` +-> bundle exec rake plugins:validate RAILS_ENV=production +Validating plugins from /plugins directory +* /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code) +* /home/git/gitlab/plugins/save_to_file.rb failure (non-zero exit code) +``` + +[hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks +[system hooks]: ../system_hooks/system_hooks.md +[webhooks]: ../user/project/integrations/webhooks.md +[5073]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5073 +[93]: https://gitlab.com/gitlab-org/gitlab-shell/merge_requests/93 + diff --git a/doc/api/commits.md b/doc/api/commits.md index 2c745d00887..55c673fd06a 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -14,6 +14,9 @@ GET /projects/:id/repository/commits | `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch | | `since` | string | no | Only commits after or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `until` | string | no | Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | +| `path` | string | no | The file path | +| `all` | boolean | no | Retrieve every commit from the repository | + ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits" diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 2957a0a5f48..6ce021cb4bf 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -47,6 +47,8 @@ Parameters: | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me` | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -162,6 +164,8 @@ Parameters: | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json diff --git a/doc/api/projects.md b/doc/api/projects.md index 9e649efea9c..b6442cfac22 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1194,6 +1194,7 @@ GET /projects/:id/hooks/:hook_id "project_id": 3, "push_events": true, "issues_events": true, + "confidential_issues_events": true, "merge_requests_events": true, "tag_push_events": true, "note_events": true, @@ -1219,12 +1220,13 @@ POST /projects/:id/hooks | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `issues_events` | boolean | no | Trigger hook on issues events | +| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | | `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | -| `wiki_events` | boolean | no | Trigger hook on wiki events | +| `wiki_page_events` | boolean | no | Trigger hook on wiki events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | @@ -1243,6 +1245,7 @@ PUT /projects/:id/hooks/:hook_id | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `issues_events` | boolean | no | Trigger hook on issues events | +| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | diff --git a/doc/api/services.md b/doc/api/services.md index 2928ab6cc75..92f12acbc73 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -619,6 +619,7 @@ Example response: "active": true, "push_events": true, "issues_events": true, + "confidential_issues_events": true, "merge_requests_events": true, "tag_push_events": true, "note_events": true, diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index f30a85b114e..23ce6a5f210 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -56,6 +56,9 @@ future GitLab releases.** | **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5 | The description of the runner as saved in GitLab | | **CI_RUNNER_ID** | 8.10 | 0.5 | The unique id of runner being used | | **CI_RUNNER_TAGS** | 8.10 | 0.5 | The defined runner tags | +| **CI_RUNNER_VERSION** | all | 10.6 | GitLab Runner version that is executing the current job | +| **CI_RUNNER_REVISION** | all | 10.6 | GitLab Runner revision that is executing the current job | +| **CI_RUNNER_EXECUTABLE_ARCH** | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) | | **CI_PIPELINE_ID** | 8.10 | 0.5 | The unique id of the current pipeline that GitLab CI uses internally | | **CI_PIPELINE_TRIGGERED** | all | all | The flag to indicate that job was [triggered] | | **CI_PIPELINE_SOURCE** | 10.0 | all | The source for this pipeline, one of: push, web, trigger, schedule, api, external. Pipelines created before 9.5 will have unknown as source | diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index f6a14de96b2..1eb90c30ebd 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -33,6 +33,40 @@ rest of the code should be as close to the CE files as possible. [single code base]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2952#note_41016454 +### Detection of EE-only files + +For each commit (except on `master`), the `ee-files-location-check` CI job tries +to detect if there are any new files that are EE-only. If any file is detected, +the job fails with an explanation of why and what to do to make it pass. + +Basically, the fix is simple: `git mv <file> ee/<file>`. + +#### How to name your branches? + +For any EE branch, the job will try to detect its CE counterpart by removing any +`ee-` prefix or `-ee` suffix from the EE branch name, and matching the last +branch that contains it. + +For instance, from the EE branch `new-shiny-feature-ee` (or +`ee-new-shiny-feature`), the job would find the corresponding CE branches: + +- `new-shiny-feature` +- `ce-new-shiny-feature` +- `new-shiny-feature-ce` +- `my-super-new-shiny-feature-in-ce` + +#### Whitelist some EE-only files that cannot be moved to `ee/` + +The `ee-files-location-check` CI job provides a whitelist of files or folders +that cannot or should not be moved to `ee/`. Feel free to open an issue to +discuss adding a new file/folder to this whitelist. + +For instance, it was decided that moving EE-only files from `qa/` to `ee/qa/` +would make it difficult to build the `gitLab-{ce,ee}-qa` Docker images and it +was [not worth the complexity]. + +[not worth the complexity]: https://gitlab.com/gitlab-org/gitlab-ee/issues/4997#note_59764702 + ### EE-only features If the feature being developed is not present in any form in CE, we don't @@ -52,6 +86,11 @@ is applied not only to models. Here's a list of other examples: - `ee/app/validators/foo_attr_validator.rb` - `ee/app/workers/foo_worker.rb` +This works because for every path that are present in CE's eager-load/auto-load +paths, we add the same `ee/`-prepended path in [`config/application.rb`]. + +[`config/application.rb`]: https://gitlab.com/gitlab-org/gitlab-ee/blob/d278b76d6600a0e27d8019a0be27971ba23ab640/config/application.rb#L41-51 + ### EE features based on CE features For features that build on existing CE features, write a module in the diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 14ac1133cc0..98e43931a02 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -36,6 +36,15 @@ If you are asynchronously adding content which contains lazy images then you nee `gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed. But in general it should be handled automatically through a `MutationObserver` in the lazy loading function. +### Animations + +Only animate `opacity` & `transform` properties. Other properties (such as `top`, `left`, `margin`, and `padding`) all cause +Layout to be recalculated, which is much more expensive. For details on this, see "Styles that Affect Layout" in +[High Performance Animations][high-perf-animations]. + +If you _do_ need to change layout (e.g. a sidebar that pushes main content over), prefer [FLIP][flip] to change expensive +properties once, and handle the actual animation with transforms. + ## Reducing Asset Footprint ### Page-specific JavaScript @@ -87,6 +96,7 @@ General tips: - Compress and minify assets wherever possible (For CSS/JS, Sprockets and webpack do this for us). - If some functionality can reasonably be achieved without adding extra libraries, avoid them. - Use page-specific JavaScript as described above to dynamically load libraries that are only needed on certain pages. +- [High Performance Animations][high-perf-animations] ------- @@ -105,3 +115,5 @@ General tips: [d3]: https://d3js.org/ [chartjs]: http://www.chartjs.org/ [page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8 +[high-perf-animations]: https://www.html5rocks.com/en/tutorials/speed/high-performance-animations/ +[flip]: https://aerotwist.com/blog/flip-your-animations/ diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 6c93c29124d..093a3ca4407 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -507,13 +507,15 @@ This is the entry point for our store. You can use the following as a guide: import Vue from 'vue'; import Vuex from 'vuex'; import * as actions from './actions'; -import * as mutations from './mutations'; +import * as getters from './getters'; +import mutations from './mutations'; Vue.use(Vuex); export default new Vuex.Store({ actions, getters, + mutations, state: { users: [], }, @@ -525,7 +527,7 @@ _Note:_ If the state of the application is too complex, an individual file for t An action commits a mutatation. In this file, we will write the actions that will call the respective mutation: ```javascript - import * as types from './mutation-types' + import * as types from './mutation_types'; export const addUser = ({ commit }, user) => { commit(types.ADD_USER, user); @@ -575,7 +577,8 @@ import { mapGetters } from 'vuex'; The only way to actually change state in a Vuex store is by committing a mutation. ```javascript - import * as types from './mutation-types' + import * as types from './mutation_types'; + export default { [types.ADD_USER](state, user) { state.users.push(user); @@ -684,4 +687,3 @@ describe('component', () => { [vuex-testing]: https://vuex.vuejs.org/en/testing.html [axios]: https://github.com/axios/axios [axios-interceptors]: https://github.com/axios/axios#interceptors - diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index c0a325a83e9..c0ce49eb40b 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -107,104 +107,28 @@ You can mark that content for translation with: ### JavaScript files -In JavaScript we added the `__()` (double underscore parenthesis) function -for translations. +In JavaScript we added the `__()` (double underscore parenthesis) function that +you can import from the `~/locale` file. For instance: -In order to test JavaScript translations you have to change the GitLab localization to other language than English and you have to generate JSON files using `bundle exec rake gettext:po_to_json` or `bundle exec rake gettext:compile`. - -## Updating the PO files with the new content - -Now that the new content is marked for translation, we need to update the PO -files with the following command: - -```sh -bundle exec rake gettext:find -``` - -This command will update the `locale/gitlab.pot` file with the newly externalized -strings and remove any strings that aren't used anymore. You should check this -file in. Once the changes are on master, they will be picked up by -[Crowdin](http://translate.gitlab.com) and be presented for translation. - -If there are merge conflicts in the `gitlab.pot` file, you can delete the file -and regenerate it using the same command. Confirm that you are not deleting any strings accidentally by looking over the diff. - -The command also updates the translation files for each language: `locale/*/gitlab.po` -These changes can be discarded, the languange files will be updated by Crowdin -automatically. - -Discard all of them at once like this: - -```sh -git checkout locale/*/gitlab.po -``` - -### Validating PO files - -To make sure we keep our translation files up to date, there's a linter that is -running on CI as part of the `static-analysis` job. - -To lint the adjustments in PO files locally you can run `rake gettext:lint`. - -The linter will take the following into account: - -- Valid PO-file syntax -- Variable usage - - Only one unnamed (`%d`) variable, since the order of variables might change - in different languages - - All variables used in the message-id are used in the translation - - There should be no variables used in a translation that aren't in the - message-id -- Errors during translation. - -The errors are grouped per file, and per message ID: - -``` -Errors in `locale/zh_HK/gitlab.po`: - PO-syntax errors - SimplePoParser::ParserErrorSyntax error in lines - Syntax error in msgctxt - Syntax error in msgid - Syntax error in msgstr - Syntax error in message_line - There should be only whitespace until the end of line after the double quote character of a message text. - Parseing result before error: '{:msgid=>["", "You are going to remove %{project_name_with_namespace}.\\n", "Removed project CANNOT be restored!\\n", "Are you ABSOLUTELY sure?"]}' - SimplePoParser filtered backtrace: SimplePoParser::ParserError -Errors in `locale/zh_TW/gitlab.po`: - 1 pipeline - <%d 條流水線> is using unknown variables: [%d] - Failure translating to zh_TW with []: too few arguments +```js +import { __ } from '~/locale'; +const label = __('Subscribe'); ``` -In this output the `locale/zh_HK/gitlab.po` has syntax errors. -The `locale/zh_TW/gitlab.po` has variables that are used in the translation that -aren't in the message with id `1 pipeline`. - -## Working with special content - - -### Just marking content for parsing - -- In Ruby/HAML: - - ```ruby - _('Subscribe') - ``` - -- In JavaScript: - - ```js - import { __ } from '../../../locale'; - const label = __('Subscribe'); - ``` +In order to test JavaScript translations you have to change the GitLab +localization to other language than English and you have to generate JSON files +using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. +### Dynamic translations Sometimes there are some dynamic translations that can't be found by the -parser when running `bundle exec rake gettext:find`. For these scenarios you can -use the [`_N` method](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#unfound-translations-with-rake-gettextfind). +parser when running `bin/rake gettext:find`. For these scenarios you can +use the [`N_` method](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#unfound-translations-with-rake-gettextfind). There is also and alternative method to [translate messages from validation errors](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#option-a). +## Working with special content + ### Interpolation - In Ruby/HAML: @@ -216,7 +140,7 @@ There is also and alternative method to [translate messages from validation erro - In JavaScript: ```js - import { __, sprintf } from '../../../locale'; + import { __, sprintf } from '~/locale'; sprintf(__('Hello %{username}'), { username: 'Joe' }) => 'Hello Joe' ``` @@ -228,24 +152,30 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. - In Ruby/HAML: ```ruby - n_('Apple', 'Apples', 3) => 'Apples' + n_('Apple', 'Apples', 3) + # => 'Apples' ``` Using interpolation: ```ruby n_("There is a mouse.", "There are %d mice.", size) % size + # => When size == 1: 'There is a mouse.' + # => When size == 2: 'There are 2 mice.' ``` - In JavaScript: ```js - n__('Apple', 'Apples', 3) => 'Apples' + n__('Apple', 'Apples', 3) + // => 'Apples' ``` Using interpolation: ```js - n__('Last day', 'Last %d days', 30) => 'Last 30 days' + n__('Last day', 'Last %d days', x) + // => When x == 1: 'Last day' + // => When x == 2: 'Last 2 days' ``` ### Namespaces @@ -267,12 +197,15 @@ Sometimes you need to add some context to the text that you want to translate s__('OpenedNDaysAgo|Opened') ``` +Note: The namespace should be removed from the translation. See the [translation +guidelines for more details](./translation.md#namespaced-strings). + ### Dates / times - In JavaScript: ```js -import { createDateTimeFormat } from '.../locale'; +import { createDateTimeFormat } from '~/locale'; const dateFormat = createDateTimeFormat({ year: 'numeric', month: 'long', day: 'numeric' }); console.log(dateFormat.format(new Date('2063-04-05'))) // April 5, 2063 @@ -282,6 +215,100 @@ This makes use of [`Intl.DateTimeFormat`]. [`Intl.DateTimeFormat`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat +## Best practices + +### Splitting sentences + +Please never split a sentence as that would assume the sentence grammar and +structure is the same in all languages. + +For instance, the following + +```js +{{ s__("mrWidget|Set by") }} +{{ author.name }} +{{ s__("mrWidget|to be merged automatically when the pipeline succeeds") }} +``` + +should be externalized as follows: + +```js +{{ sprintf(s__("mrWidget|Set by %{author} to be merged automatically when the pipeline succeeds"), { author: author.name }) }} +``` + +When in doubt, try to follow the best practices described in this [Mozilla +Developer documentation][mdn]. + +[mdn]: https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Splitting + +## Updating the PO files with the new content + +Now that the new content is marked for translation, we need to update the PO +files with the following command: + +```sh +bin/rake gettext:find +``` + +This command will update the `locale/gitlab.pot` file with the newly externalized +strings and remove any strings that aren't used anymore. You should check this +file in. Once the changes are on master, they will be picked up by +[Crowdin](http://translate.gitlab.com) and be presented for translation. + +If there are merge conflicts in the `gitlab.pot` file, you can delete the file +and regenerate it using the same command. Confirm that you are not deleting any strings accidentally by looking over the diff. + +The command also updates the translation files for each language: `locale/*/gitlab.po` +These changes can be discarded, the languange files will be updated by Crowdin +automatically. + +Discard all of them at once like this: + +```sh +git checkout locale/*/gitlab.po +``` + +### Validating PO files + +To make sure we keep our translation files up to date, there's a linter that is +running on CI as part of the `static-analysis` job. + +To lint the adjustments in PO files locally you can run `rake gettext:lint`. + +The linter will take the following into account: + +- Valid PO-file syntax +- Variable usage + - Only one unnamed (`%d`) variable, since the order of variables might change + in different languages + - All variables used in the message-id are used in the translation + - There should be no variables used in a translation that aren't in the + message-id +- Errors during translation. + +The errors are grouped per file, and per message ID: + +``` +Errors in `locale/zh_HK/gitlab.po`: + PO-syntax errors + SimplePoParser::ParserErrorSyntax error in lines + Syntax error in msgctxt + Syntax error in msgid + Syntax error in msgstr + Syntax error in message_line + There should be only whitespace until the end of line after the double quote character of a message text. + Parseing result before error: '{:msgid=>["", "You are going to remove %{project_name_with_namespace}.\\n", "Removed project CANNOT be restored!\\n", "Are you ABSOLUTELY sure?"]}' + SimplePoParser filtered backtrace: SimplePoParser::ParserError +Errors in `locale/zh_TW/gitlab.po`: + 1 pipeline + <%d 條流水線> is using unknown variables: [%d] + Failure translating to zh_TW with []: too few arguments +``` + +In this output the `locale/zh_HK/gitlab.po` has syntax errors. +The `locale/zh_TW/gitlab.po` has variables that are used in the translation that +aren't in the message with id `1 pipeline`. + ## Adding a new language Let's suppose you want to add translations for a new language, let's say French. @@ -300,14 +327,14 @@ Let's suppose you want to add translations for a new language, let's say French. 1. Next, you need to add the language: ```sh - bundle exec rake gettext:add_language[fr] + bin/rake gettext:add_language[fr] ``` If you want to add a new language for a specific region, the command is similar, you just need to separate the region with an underscore (`_`). For example: ```sh - bundle exec rake gettext:add_language[en_GB] + bin/rake gettext:add_language[en_GB] ``` Please note that you need to specify the region part in capitals. @@ -321,7 +348,7 @@ Let's suppose you want to add translations for a new language, let's say French. containing the translations: ```sh - bundle exec rake gettext:compile + bin/rake gettext:compile ``` 1. In order to see the translated content we need to change our preferred language diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index ece9a9bc0fe..9aa3fb07abf 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -15,6 +15,7 @@ are very appreciative of the work done by translators and proofreaders! - Dutch - Esperanto - French + - Rémy Coutable - [GitLab](https://gitlab.com/rymai), [Crowdin](https://crowdin.com/profile/rymai) - German - Italian - Paolo Falomo - [GitLab](https://gitlab.com/paolofalomo), [Crowdin](https://crowdin.com/profile/paolo.falomo) diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index b34ec754742..99c0fe6db1d 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -37,33 +37,43 @@ Comments can be added to discuss a translation with the community. Remember to **Save** each translation. -## Translation Guidelines +## General Translation Guidelines Be sure to check the following guidelines before you translate any strings. +### Namespaced strings + +When an externalized string is prepended with a namespace, e.g. +`s_('OpenedNDaysAgo|Opened')`, the namespace should be removed from the final +translation. +For example in French `OpenedNDaysAgo|Opened` would be translated to +`Ouvert•e`, not `OpenedNDaysAgo|Ouvert•e`. + ### Technical terms -Technical terms should be treated like proper nouns and not be translated. -This helps maintain a logical connection and consistency between tools (e.g. `git` client) and -GitLab. +Some technical terms should be treated like proper nouns and not be translated. -Technical terms that should always be in English are noted in the glossary when using -[translate.gitlab.com](https://translate.gitlab.com). +Technical terms that should always be in English are noted in the glossary when +using [translate.gitlab.com](https://translate.gitlab.com). + +This helps maintain a logical connection and consistency between tools (e.g. +`git` client) and GitLab. ### Formality The level of formality used in software varies by language. -For example, in French we translate `you` as the informal `tu`. +For example, in French we translate `you` as the formal `vous`. -You can refer to other translated strings and notes in the glossary to assist determining a -suitable level of formality. +You can refer to other translated strings and notes in the glossary to assist +determining a suitable level of formality. ### Inclusive language [Diversity] is one of GitLab's values. -We ask you to avoid translations which exclude people based on their gender or ethnicity. -In languages which distinguish between a male and female form, -use both or choose a neutral formulation. +We ask you to avoid translations which exclude people based on their gender or +ethnicity. +In languages which distinguish between a male and female form, use both or +choose a neutral formulation. For example in German, the word "user" can be translated into "Benutzer" (male) or "Benutzerin" (female). Therefore "create a new user" would translate into "Benutzer(in) anlegen". @@ -74,3 +84,14 @@ Therefore "create a new user" would translate into "Benutzer(in) anlegen". To propose additions to the glossary please [open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues). + +## French Translation Guidelines + +### Inclusive language in French + +In French, we should follow the guidelines from [ecriture-inclusive.fr]. For +instance: + +- Utilisateur•rice•s + +[ecriture-inclusive.fr]: http://www.ecriture-inclusive.fr/ diff --git a/doc/install/installation.md b/doc/install/installation.md index 4dfc03d0fe0..170d92faa09 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -93,9 +93,9 @@ Is the system packaged Git too old? Remove it and compile from source. # Download and compile from source cd /tmp - curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.14.3.tar.gz - echo '023ffff6d3ba8a1bea779dfecc0ed0bb4ad68ab8601d14435dd8c08416f78d7f git-2.14.3.tar.gz' | shasum -a256 -c - && tar -xzf git-2.14.3.tar.gz - cd git-2.14.3/ + curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.16.2.tar.gz + echo '9acc4339b7a2ab484eea69d705923271682b7058015219cf5a7e6ed8dee5b5fb git-2.16.2.tar.gz' | shasum -a256 -c - && tar -xzf git-2.16.2.tar.gz + cd git-2.16.2/ ./configure make prefix=/usr/local all diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 3ae98adc465..f8a7dd6b1dc 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -109,8 +109,7 @@ in your SAML IdP: 1. Change the value of `issuer` to a unique name, which will identify the application to the IdP. -1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. For the changes to take effect, you must [reconfigure][] GitLab if you installed via Omnibus or [restart GitLab][] if you installed from source. 1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified in `issuer`. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index ea7b1c9a0ed..650d60f1585 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -36,12 +36,16 @@ GFM honors the markdown specification in how [paragraphs and line breaks are han A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Line-breaks, or softreturns, are rendered if you end a line with two or more spaces: - Roses are red [followed by two or more spaces] +[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) +[//]: # (They are needed for the Markdown text to render correctly.) + Roses are red [followed by two or more spaces] Violets are blue Sugar is sweet -Roses are red +[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) +[//]: # (They are needed for the Markdown text to render correctly.) +Roses are red Violets are blue Sugar is sweet diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 0de89f90e21..16027744164 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -34,7 +34,7 @@ With **[GitLab Enterprise Edition][ee]**, you can also: - View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) (available only in GitLab Premium) - Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers (available in GitLab Starter) - [Squash and merge](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html) for a cleaner commit history (available in GitLab Starter) -- Analise the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) (available in GitLab Starter) +- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) (available in GitLab Starter) ## Use cases |