Add latest changes from gitlab-org/gitlab@master

3 files changed, 81 insertions, 5 deletions

diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md
index 70385b666a4..4445efa823a 100644
--- a/doc/development/sidekiq_style_guide.md
+++ b/doc/development/sidekiq_style_guide.md
@@ -64,6 +64,63 @@ the extra jobs will take resources away from jobs from workers that were already
 there, if the resources available to the Sidekiq process handling the namespace
 are not adjusted appropriately.
 
+## Idempotent Jobs
+
+It's known that a job can fail for multiple reasons, for example, network outages or bugs.
+In order to address this, Sidekiq has a built-in retry mechanism that is
+used by default by most workers within GitLab.
+
+It's expected that a job can run again after a failure without major side-effects for the
+application or users, which is why Sidekiq encourages
+jobs to be [idempotent and transactional](https://github.com/mperham/sidekiq/wiki/Best-Practices#2-make-your-job-idempotent-and-transactional).
+
+As a general rule, a worker can be considered idempotent if:
+
+- It can safely run multiple times with the same arguments.
+- Application side-effects are expected to happen only once
+  (or side-effects of a second run are not impactful).
+
+A good example of that would be a cache expiration worker.
+
+### Ensuring a worker is idempotent
+
+Make sure the worker tests pass using the following shared example:
+
+```ruby
+include_examples 'an idempotent worker' do
+  it 'marks the MR as merged' do
+    # Using subject inside this block will process the job multiple times
+    subject
+
+    expect(merge_request.state).to eq('merged')
+  end
+end
+```
+
+Use the `perform_multiple` method directly instead of `job.perform` (this
+helper method is automatically included for workers).
+
+### Declaring a worker as idempotent
+
+```ruby
+class IdempotentWorker
+  include ApplicationWorker
+
+  # Declares a worker is idempotent and can
+  # safely run multiple times.
+  idempotent!
+
+  # ...
+end
+```
+
+It's encouraged to only have the `idempotent!` call in the top-most worker class, even if
+the `perform` method is defined in another class or module.
+
+NOTE: **Note:**
+Note that a cop will fail if the worker class is not marked as idempotent.
+Consider skipping the cop if you're not confident your job can safely run multiple times.
+
 ## Latency Sensitive Jobs
 
 If a large number of background jobs get scheduled at once, queueing of jobs may
diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md
index 4af6f47ce7b..52fcad8dd80 100644
--- a/doc/user/project/insights/index.md
+++ b/doc/user/project/insights/index.md
@@ -61,6 +61,7 @@ bugsCharts:
   title: "Charts for bugs"
   charts:
     - title: "Monthly bugs created"
+      description: "Open bugs created per month"
       type: bar
       query:
         issuable_type: issue
@@ -77,6 +78,7 @@ For example, here's single chart definition:
 
 ```yaml
 - title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -96,6 +98,7 @@ The following table lists available parameters for charts:
 | Keyword                                            | Description |
 |:---------------------------------------------------|:------------|
 | [`title`](#title)                                  | The title of the chart. This will displayed on the Insights page. |
+| [`description`](#description)                      | A description for the individual chart. This will be displayed above the relevant chart. |
 | [`type`](#type)                                    | The type of chart: `bar`, `line` or `stacked-bar`. |
 | [`query`](#query)                                  | A hash that defines the conditions for issues / merge requests to be part of the chart. |
 
@@ -114,6 +117,17 @@ monthlyBugsCreated:
   title: "Monthly bugs created"
 ```
 
+### `description`
+
+The `description` text is displayed above the chart, but below the title. It's used
+to give extra details regarding the chart, for example:
+
+```yaml
+monthlyBugsCreated:
+  title: "Monthly bugs created"
+  description: "Open bugs created per month"
+```
+
 ### `type`
 
 `type` is the chart type.
@@ -145,6 +159,7 @@ Example:
 ```yaml
 monthlyBugsCreated:
   title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -283,6 +298,7 @@ a group's insights:
 ```yaml
 monthlyBugsCreated:
   title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -311,6 +327,7 @@ bugsCharts:
   title: "Charts for bugs"
   charts:
     - title: "Monthly bugs created"
+      description: "Open bugs created per month"
       type: bar
       <<: *projectsOnly
       query:
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md
index 7fa758b8a51..3d44f342715 100644
--- a/doc/user/project/merge_requests/accessibility_testing.md
+++ b/doc/user/project/merge_requests/accessibility_testing.md
@@ -33,17 +33,19 @@ defined in that template.
 Add the following to your `.gitlab-ci.yml` file:
 
 ```yaml
-include:
-  template: Verify/Accessibility.gitlab-ci.yml
+variables:
+  a11y_urls: "https://about.gitlab.com"
 
-a11y:
-  variables:
-    a11y_urls: https://example.com https://example.com/another-page
+include:
+  - remote: "https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml"
 ```
 
 The example above will create an `a11y` job in your CI/CD pipeline and will run
 Pa11y against the webpage you defined in `a11y_urls` to build a report.
 
+NOTE: **Note:**
+Only one URL may be currently passed into `a11y_urls`.
+
 The full HTML Pa11y report will be saved as an artifact that can be [viewed directly in your browser](../pipelines/job_artifacts.md#browsing-artifacts).
 
 NOTE: **Note:**