Add latest changes from gitlab-org/gitlab@master

3 files changed, 90 insertions, 5 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index a9d8941488f..acba09986fb 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -196,13 +196,12 @@ Every GitLab instance includes the documentation, which is available at `/help`
 There are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this
 practice and instead link out from the GitLab application to <https://docs.gitlab.com> URLs.
 
-The documentation available online on <https://docs.gitlab.com> is continuously
-deployed every hour from the `master` branch of GitLab, Omnibus, and Runner. Therefore,
-once a merge request gets merged, it will be available online on the same day.
-However, they will be shipped (and available on `/help`) within the milestone assigned
+The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore,
+after a merge request gets merged, it will be available online on the same day.
+However, it will be shipped (and available on `/help`) within the milestone assigned
 to the MR.
 
-For instance, let's say your merge request has a milestone set to 11.3, which
+For example, let's say your merge request has a milestone set to 11.3, which
 will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be
 available online on 2018-09-15, but, as the feature freeze date has passed, if
 the MR does not have a "pick into 11.3" label, the milestone has to be changed
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 407633c24df..5dddb47a033 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -769,6 +769,74 @@ nicely on different mobile devices.
 - [Syntax highlighting for code blocks](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) is available for many languages.
 - For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
 
+## GitLab SVG icons
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/issues/384) in GitLab 12.7.
+
+You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) directly
+in the documentation.
+
+This way, you can achieve a consistent look when writing about interacting with GitLab UI elements.
+
+Usage examples:
+
+- Icon with default size (16px): `**{icon-name}**`
+
+  Example: `**{tanuki}**` renders as: **{tanuki}**.
+- Icon with custom size: `**{icon-name, size}**`
+
+  Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72
+
+  Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**.
+- Icon with custom size and class: `**{icon-name, size, class-name}**`.
+
+  You can access any class available to this element in GitLab docs CSS.
+
+  Example with `float-right`, a
+  [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/):
+  `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}**
+
+### Using GitLab SVGs to describe UI elements
+
+When using GitLab SVGs to describe screen elements, also include the name or tooltip of the element as text.
+
+For example, for references to the Admin Area:
+
+- Correct: `**{admin}** **Admin Area > Settings**` (**{admin}** **Admin Area > Settings**)
+- Incorrect: `**{admin}** **> Settings**` (**{admin}** **> Settings**)
+
+This will ensure that the source Markdown remains readable and should help with accessibility.
+
+The following are examples of source Markdown for menu items with their published output:
+
+```md
+1. Go to **{home}** **Project overview > Details**
+1. Go to **{doc-text}** **Repository > Branches**
+1. Go to **{issues}** **Issues > List**
+1. Go to **{merge-request}** **Merge Requests**
+1. Go to **{rocket}** **CI/CD > Pipelines**
+1. Go to **{shield}** **Security & Compliance > Configuration**
+1. Go to **{cloud-gear}** **Operations > Metrics**
+1. Go to **{package}** **Packages > Container Registry**
+1. Go to **{chart}** **Project Analytics > Code Review**
+1. Go to **{book}** **Wiki**
+1. Go to **{snippet}** **Snippets**
+1. Go to **{users}** **Members**
+```
+
+1. Go to **{home}** **Project overview > Details**
+1. Go to **{doc-text}** **Repository > Branches**
+1. Go to **{issues}** **Issues > List**
+1. Go to **{merge-request}** **Merge Requests**
+1. Go to **{rocket}** **CI/CD > Pipelines**
+1. Go to **{shield}** **Security & Compliance > Configuration**
+1. Go to **{cloud-gear}** **Operations > Metrics**
+1. Go to **{package}** **Packages > Container Registry**
+1. Go to **{chart}** **Project Analytics > Code Review**
+1. Go to **{book}** **Wiki**
+1. Go to **{snippet}** **Snippets**
+1. Go to **{users}** **Members**
+
 ## Alert boxes
 
 Whenever you need to call special attention to particular sentences,
diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md
index 386baf825b8..488d7ae6762 100644
--- a/doc/development/i18n/externalization.md
+++ b/doc/development/i18n/externalization.md
@@ -77,6 +77,24 @@ Or:
 hello = _("Hello world!")
 ```
 
+Be careful when translating strings at the class or module level since these would only be
+evaluated once at class load time.
+
+For example:
+
+```ruby
+validates :group_id, uniqueness: { scope: [:project_id], message: _("already shared with this group") }
+```
+
+This would be translated when the class is loaded and result in the error message
+always being in the default locale.
+
+Active Record's `:message` option accepts a `Proc`, so we can do this instead:
+
+```ruby
+validates :group_id, uniqueness: { scope: [:project_id], message: -> (object, data) { _("already shared with this group") } }
+```
+
 NOTE: **Note:** Messages in the API (`lib/api/` or `app/graphql`) do
 not need to be externalised.