Add latest changes from gitlab-org/gitlab@master

3 files changed, 114 insertions, 92 deletions

diff --git a/doc/architecture/blueprints/ci_scale/index.md b/doc/architecture/blueprints/ci_scale/index.md
index 3e9fbc534d5..af1cac42241 100644
--- a/doc/architecture/blueprints/ci_scale/index.md
+++ b/doc/architecture/blueprints/ci_scale/index.md
@@ -5,7 +5,7 @@ comments: false
 description: 'Improve scalability of GitLab CI/CD'
 ---
 
-# Next CI/CD scale target: 20M builds per day by 2024
+# CI/CD Scaling
 
 ## Summary
 
@@ -20,13 +20,8 @@ store all the builds in PostgreSQL in `ci_builds` table, and because we are
 creating more than [2 million builds each day on GitLab.com](https://docs.google.com/spreadsheets/d/17ZdTWQMnTHWbyERlvj1GA7qhw_uIfCoI5Zfrrsh95zU),
 we are reaching database limits that are slowing our development velocity down.
 
-On February 1st, 2021, a billionth CI/CD job was created and the number of
-builds is growing exponentially. We will run out of the available primary keys
-for builds before December 2021 unless we improve the database model used to
-store CI/CD data.
-
-We expect to see 20M builds created daily on GitLab.com in the first half of
-2024.
+On February 1st, 2021, GitLab.com surpased 1 billion CI/CD builds created and the number of
+builds continues to grow exponentially.
 
 ![CI builds cumulative with forecast](ci_builds_cumulative_forecast.png)
 
@@ -60,8 +55,8 @@ that have the same problem.
 
 Primary keys problem will be tackled by our Database Team.
 
-Status: As of October 2021 the primary keys in CI tables have been migrated to
-big integers.
+**Status**: As of October 2021 the primary keys in CI tables have been migrated
+to big integers.
 
 ### The table is too large
 
@@ -84,6 +79,14 @@ seem fine in the development environment may not work on GitLab.com. The
 difference in the dataset size between the environments makes it difficult to
 predict the performance of even the most simple queries.
 
+Team members and the wider community members are struggling to contribute the
+Verify area, because we restricted the possibility of extending `ci_builds`
+even further. Our static analysis tools prevent adding more columns to this
+table. Adding new queries is unpredictable because of the size of the dataset
+and the amount of queries executed using the table. This significantly hinders
+the development velocity and contributes to incidents on the production
+environment.
+
 We also expect a significant, exponential growth in the upcoming years.
 
 One of the forecasts done using [Facebook's
@@ -94,6 +97,10 @@ sustain in upcoming years.
 
 ![CI builds daily forecast](ci_builds_daily_forecast.png)
 
+**Status**: As of October 2021 we reduced the growth rate of `ci_builds` table
+by writing build options and variables to `ci_builds_metadata` table. We plan
+to ship futher improvements that will be described in a separate blueprint.
+
 ### Queuing mechanisms are using the large table
 
 Because of how large the table is, mechanisms that we use to build queues of
@@ -114,8 +121,8 @@ table that will accelerate SQL queries used to build
 queues](https://gitlab.com/gitlab-org/gitlab/-/issues/322766) and we want to
 explore them.
 
-Status: the new architecture [has been implemented on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5909#note_680407908).
-
+**Status**: As of October 2021 the new architecture [has been implemented on
+GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5909#note_680407908).
 The following epic tracks making it generally available: [Make the new pending
 builds architecture generally available](
 https://gitlab.com/groups/gitlab-org/-/epics/6954).
@@ -136,17 +143,8 @@ columns, tables, partitions or database shards.
 
 Effort to improve background migrations will be owned by our Database Team.
 
-Status: In progress.
-
-### Development velocity is negatively affected
-
-Team members and the wider community members are struggling to contribute the
-Verify area, because we restricted the possibility of extending `ci_builds`
-even further. Our static analysis tools prevent adding more columns to this
-table. Adding new queries is unpredictable because of the size of the dataset
-and the amount of queries executed using the table. This significantly hinders
-the development velocity and contributes to incidents on the production
-environment.
+**Status**: In progress. We plan to ship further improvements that will be
+described in a separate architectural blueprint.
 
 ## Proposal
 
@@ -157,32 +155,34 @@ First, we want to focus on things that are urgently needed right now. We need
 to fix primary keys overflow risk and unblock other teams that are working on
 database partitioning and sharding.
 
-We want to improve situation around bottlenecks that are known already, like
-queuing mechanisms using the large table and things that are holding other
-teams back.
+We want to improve known bottlenecks, like
+builds queuing mechanisms that is using the large table, and other things that
+are holding other teams back.
 
 Extending CI/CD metrics is important to get a better sense of how the system
 performs and to what growth should we expect. This will make it easier for us
 to identify bottlenecks and perform more advanced capacity planning.
 
-As we work on first iterations we expect our Database Sharding team and
-Database Scalability Working Group to make progress on patterns we will be able
-to use to partition the large CI/CD dataset. We consider the strong time-decay
-effect, related to the diminishing importance of pipelines with time, as an
-opportunity we might want to seize.
+Next step is to better understand how we can leverage strong time-decay
+characteristic of CI/CD data. This might help us to partition CI/CD dataset to
+reduce the size of CI/CD database tables.
 
 ## Iterations
 
 Work required to achieve our next CI/CD scaling target is tracked in the
-[GitLab CI/CD 20M builds per day scaling
-target](https://gitlab.com/groups/gitlab-org/-/epics/5745) epic.
+[CI/CD Scaling](https://gitlab.com/groups/gitlab-org/-/epics/5745) epic.
+
+1. ✓ Migrate primary keys to big integers on GitLab.com.
+1. ✓ Implement the new architecture of builds queuing on GitLab.com.
+1. Make the new builds queuing architecture generally available.
+1. Partition CI/CD data using time-decay pattern.
 
 ## Status
 
 |-------------|--------------|
 | Created at  | 21.01.2021   |
 | Approved at | 26.04.2021   |
-| Updated at  | 28.10.2021   |
+| Updated at  | 06.12.2021   |
 
 Status: In progress.
 
@@ -215,6 +215,7 @@ Domain experts:
 | Area                         | Who
 |------------------------------|------------------------|
 | Domain Expert / Verify       | Fabio Pitino           |
+| Domain Expert / Verify       | Marius Bobin           |
 | Domain Expert / Database     | Jose Finotto           |
 | Domain Expert / PostgreSQL   | Nikolay Samokhvalov    |
 
diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md
index f8ee29e6904..27c29a1ed7c 100644
--- a/doc/development/deprecation_guidelines/index.md
+++ b/doc/development/deprecation_guidelines/index.md
@@ -23,7 +23,9 @@ deprecated.
 
 A feature can be deprecated at any time, provided there is a viable alternative.
 
-Deprecations should be announced via [release posts](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations).
+Deprecations should be announced on the [Deprecated feature removal schedule](../../update/deprecations.md).
+
+For steps to create a deprecation entry, see [Deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations).
 
 ## When can a feature be removed/changed?
 
diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md
index bc8c8fca5b5..f7e9d8f64b0 100644
--- a/doc/user/project/releases/index.md
+++ b/doc/user/project/releases/index.md
@@ -1,5 +1,4 @@
 ---
-type: reference, howto
 stage: Release
 group: Release
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
@@ -9,26 +8,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7.
 
-To introduce a checkpoint in your source code history, you can assign a
-[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) at the moment of release.
-However, in most cases, your users need more than just the raw source code.
-They need compiled objects or other assets output by your CI/CD system.
+In GitLab, a release enables you to create a snapshot of your project for your users, including
+installation packages and release notes. You can create a GitLab release on any branch. Creating a
+release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the
+release point in the source code.
 
-A GitLab Release can be:
+WARNING:
+Deleting a Git tag associated with a release also deletes the release.
+
+A release can include:
 
 - A snapshot of the source code of your repository.
 - [Generic packages](../../packages/generic_packages/index.md) created from job artifacts.
 - Other metadata associated with a released version of your code.
+- Release notes.
 
-You can create a GitLab release on any branch. When you create a release:
+When you [create a release](#create-a-release):
 
 - GitLab automatically archives source code and associates it with the release.
 - GitLab automatically creates a JSON file that lists everything in the release,
   so you can compare and audit releases. This file is called [release evidence](#release-evidence).
-- You can add release notes and a message for the tag associated with the release.
 
-After you create a release, you can [associate milestones with it](#associate-milestones-with-a-release),
-and attach [release assets](#release-assets), like runbooks or packages.
+When you create a release, or after, you can:
+
+- Add release notes.
+- Add a message for the Git tag associated with the release.
+- [Associate milestones with it](#associate-milestones-with-a-release).
+- Attach [release assets](#release-assets), like runbooks or packages.
 
 ## View releases
 
@@ -57,38 +63,73 @@ switch between ascending or descending order, select **Sort order**.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI.
 
-You can create a release in the user interface, or by using the
-[Releases API](../../../api/releases/index.md#create-a-release).
-We recommend using the API to create releases as one of the last steps in your
-CI/CD pipeline.
+You can create a release:
 
-Only users with at least the Developer role can create releases.
-Read more about [Release permissions](#release-permissions).
+- [Using a job in your CI/CD pipeline](#create-a-release-by-using-a-cicd-job).
+- [In the Releases page](#create-a-release-in-the-releases-page).
+- [In the Tags page](#create-a-release-in-the-tags-page).
+- Using the [Releases API](../../../api/releases/index.md#create-a-release).
+
+We recommend creating a release as one of the last steps in your CI/CD pipeline.
 
-To create a new release through the GitLab UI:
+Prerequisites:
 
+- You must have at least the Developer role for a project. For more information, read
+[Release permissions](#release-permissions).
+
+### Create a release in the Releases page
+
+To create a release in the Releases page:
+
+1. On the top bar, select **Menu > Projects** and find your project.
 1. On the left sidebar, select **Deployments > Releases** and select **New release**.
-1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type
-   in a new tag name. Selecting an existing tag that is already associated with
-   a release will result in a validation error.
-1. If creating a new tag, open the **Create from** dropdown. Select a
-   branch, tag, or commit SHA to use when creating the new tag.
-1. Optionally, fill out any additional information about the release, such as its
-   [title](#title), [milestones](#associate-milestones-with-a-release),
-   [release notes](#release-notes-description), or [assets links](#links).
-1. Click **Create release**.
-
-## Create a release by using a CI/CD job
+1. From the [**Tag name**](#tag-name) dropdown, either:
+   - Select an existing Git tag. Selecting an existing tag that is already associated with a release
+     results in a validation error.
+   - Enter a new Git tag name.
+      1. From the **Create from** dropdown, select a branch or commit SHA to use when creating the
+         new tag.
+1. Optional. Enter additional information about the release, including:
+   - [Title](#title).
+   - [Milestones](#associate-milestones-with-a-release).
+   - [Release notes](#release-notes-description).
+   - [Asset links](#links).
+1. Select **Create release**.
+
+### Create a release in the Tags page
+
+To create a release in the Tags page, add release notes to either an existing or a new Git tag.
+
+To add release notes to a new Git tag:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Repository > Tags**.
+1. Select **New tag**.
+1. Optional. Enter a tag message in the **Message** text box.
+1. In the **Release notes** text box, enter the release's description.
+   You can use Markdown and drag and drop files to this text box.
+1. Select **Create tag**.
+
+To edit release notes of an existing Git tag:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Repository > Tags**.
+1. Select **Edit release notes** (**{pencil}**).
+1. In the **Release notes** text box, enter the release's description.
+   You can use Markdown and drag and drop files to this text box.
+1. Select **Save changes**.
+
+### Create a release by using a CI/CD job
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7.
 
 You can create a release directly as part of the GitLab CI/CD pipeline
-by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition.
+by using the [`release` keyword](../../../ci/yaml/index.md#release) in the job definition.
 
-The release is created only if the job processes without error. If the Rails API returns an error
-during release creation, the release job fails.
+The release is created only if the job processes without error. If the API returns an error during
+release creation, the release job fails.
 
-### CI/CD example of the `release` keyword
+#### CI/CD example of the `release` keyword
 
 To create a release when you push a Git tag, or when you add a Git tag
 in the UI by going to **Repository > Tags**:
@@ -207,7 +248,7 @@ which requires the text representation of the certificate.
 
 ### `release-cli` command line
 
-The entries under the `release` node are transformed into a `bash` command line and sent
+The entries under the `release` node are transformed into Bash commands and sent
 to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
 You can also call the `release-cli` directly from a `script` entry.
 
@@ -255,7 +296,8 @@ release tag. When the `released_at` date and time has passed, the badge is autom
 
 ## Edit a release
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6.
+> - Asset link editing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10.
 
 Only users with at least the Developer role can edit releases.
 Read more about [Release permissions](#release-permissions).
@@ -271,29 +313,6 @@ You can edit the release title, notes, associated milestones, and asset links.
 To change the release date use the
 [Releases API](../../../api/releases/index.md#update-a-release).
 
-## Add release notes to Git tags
-
-If you have an existing Git tag, you can add release notes to it.
-
-You can do this in the user interface, or by using the [Releases API](../../../api/releases/index.md).
-We recommend using the API to add release notes as one of the last steps in your CI/CD release pipeline.
-
-In the interface, to add release notes to a new Git tag:
-
-1. Navigate to your project's **Repository > Tags**.
-1. Click **New tag**.
-1. In the **Release notes** field, enter the release's description.
-   You can use Markdown and drag and drop files to this field.
-1. Click **Create tag**.
-
-In the interface, to add release notes to an existing Git tag:
-
-1. Navigate to your project's **Repository > Tags**.
-1. Click **Edit release notes** (the pencil icon).
-1. In the **Release notes** field, enter the release's description.
-   You can use Markdown in this field, and drag and drop files to it.
-1. Click **Save changes**.
-
 ## Associate milestones with a release
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29020) in GitLab 12.5.