Skip to content

G
gitlab-ce
Commit b4e456dd authored by Evan Read's avatar Evan Read Committed by Achilleas Pipinellis
Browse files
Options

Improve documentation release process docs

parent ea5ce5a8
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 127 deletions
doc/development/documentation/site_architecture/release_process.md
View file @ b4e456dd
......@@ -4,191 +4,165 @@ group: unassigned
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
---
# GitLab Docs monthly release process
# Monthly release process
When a new GitLab version is released on the 22nd, we need to create the respective
single Docker image, and update some files so that the dropdown works correctly.
When a new GitLab version is released on the 22nd, we need to release the published documentation
for the new version.
## 1. Add the chart version
This should be done as soon as possible after the GitLab version is announced, so that:
Since the charts use a different version number than all the other GitLab
products, we need to add a
[version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html):
- The published documentation includes the three most recent minor releases of the current major
version, and the most recent minor releases of the last two major versions. For example 13.9,
13.8, 13.7, 12.10, and 11.11.
- Documentation updates after the 22nd are for the next release. The versions drop down
should have the current milestone with `-pre` appended to it, for example `13.10-pre`.
The charts stable branch is not created automatically like the other products.
There's an [issue to track this](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/1442).
It is usually created on the 21st or the 22nd.
Each documentation release:
To add a new charts version:
- Has a dedicated branch, named in the format `XX.yy`.
- Has a Docker image that contains a build of that branch.
For example:
- For [GitLab 13.9](https://docs.gitlab.com/13.9/index.html), the
[stable branch](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/13.9) and Docker image:
[`registry.gitlab.com/gitlab-org/gitlab-docs:13.9`](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635).
- For [GitLab 13.8](https://docs.gitlab.com/13.8/index.html), the
[stable branch](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/13.8) and Docker image:
[`registry.gitlab.com/gitlab-org/gitlab-docs:13.8`](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635).
To set up a documentation release, follow these steps:
1. [Add the charts version](#add-chart-version), so that the documentation is built using the
[version of the charts project that maps to](https://docs.gitlab.com/charts/installation/version_mappings.html)
the GitLab release. This step may have been completed already.
1. [Create a stable branch and Docker image](#create-stable-branch-and-docker-image-for-release) for
the new version.
1. [Create a release merge request](#create-release-merge-request) for the new version, which
updates the version dropdown menu for the current documentation and adds the release to the
Docker configuration. For example, the
[release merge request for 13.9](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1555).
1. [Update the three online versions](#update-dropdown-for-online-versions), so that they display the new release on their
version dropdown menus. For example:
- The merge request to [update the 13.9 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1556).
- The merge request to [update the 13.8 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1557).
- The merge request to [update the 13.7 version dropdown menu for the 13.9 release](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1558).
1. [Merge the release merge request and run the necessary Docker image builds](#merge-release-merge-request-and-run-docker-image-builds).
## Add chart version
To add a new charts version for the release:
1. Make sure you're in the root path of the `gitlab-docs` repository.
1. Open `content/_data/chart_versions.yaml` and add the new stable branch version using the
version mapping. Note that only the `major.minor` version is needed.
[version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html). Only the
`major.minor` version is needed.
1. Create a new merge request and merge it.
NOTE:
It can be handy to create the future mappings since they are pretty much known.
In that case, when a new GitLab version is released, you don't have to repeat
this first step.
If you have time, add anticipated future mappings to `content/_data/chart_versions.yaml`. This saves
a step for the next GitLab release.
## 2. Create an image for a single version
## Create stable branch and Docker image for release
The single docs version must be created before the release merge request, but
this needs to happen when the stable branches for all products have been created.
To create a stable branch and Docker image for the release:
1. Make sure you're in the root path of the `gitlab-docs` repository.
1. Run the Rake task to create the single version:
1. Run the Rake task to create the single version. For example, to create the 13.9 release branch
and perform others tasks:
```shell
./bin/rake "release:single[12.0]"
./bin/rake "release:single[13.9]"
```
A new `Dockerfile.12.0` should have been created and `.gitlab-ci.yml` should
have the branches variables updated into a new branch. They are automatically
committed.
A branch for the release is created, a new `Dockerfile.13.9` is created, and `.gitlab-ci.yml`
has branches variables updated into a new branch. These files are automatically committed.
1. Push the newly created branch, but **don't create a merge request**. After you push, the
`image:docs-single` job creates a new Docker image tagged with the name of the branch you created
earlier. You can see the Docker image in the `registry` environment at
<https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry>.
1. Push the newly created branch, but **don't create a merge request**.
After you push, the `image:docs-single` job creates a new Docker image
tagged with the branch name you created in the first step. In the end, the
image is uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry)
and it is listed under the `registry` environment folder at
`https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry` (must
have developer access).
For example, see [the 13.9 release pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/260288747).
Optionally, you can test locally by building the image and running it:
Optionally, you can test locally by:
```shell
docker build -t docs:12.0 -f Dockerfile.12.0 .
docker run -it --rm -p 4000:4000 docs:12.0
```
1. Building the image and running it. For example, for GitLab 13.9 documentation:
Visit `http://localhost:4000/12.0/` to see if everything works correctly.
```shell
docker build -t docs:13.9 -f Dockerfile.13.9 .
docker run -it --rm -p 4000:4000 docs:13.9
```
## 3. Create the release merge request
1. Visiting <http://localhost:4000/13.9/> to see if everything works correctly.
## Create release merge request
NOTE:
To be [automated](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/750).
An [epic is open](https://gitlab.com/groups/gitlab-org/-/epics/4361) to automate this step.
Now it's time to create the monthly release merge request that adds the new
version and rotates the old one:
To create the release merge request for the release:
1. Make sure you're in the root path of the `gitlab-docs` repository.
1. Create a branch `release-X-Y`:
1. Create a branch `release-X-Y`. For example:
```shell
git checkout master
git checkout -b release-12-0
git checkout -b release-13-9
```
1. **Rotate the online and offline versions:**
At any given time, there are 4 browsable online versions: one pulled from
the upstream master branches (docs for GitLab.com) and the three latest
stable versions.
1. Edit `content/_data/versions.yaml` and update the lists of versions to reflect the new release:
Edit `content/_data/versions.yaml` and rotate the versions to reflect the
new changes:
- Add the latest version to the `online:` section.
- Move the oldest version in `online:` to the `offline:` section. There should now be three
versions in `online:`.
- `online`: The 3 latest stable versions.
- `offline`: All the previous versions offered as an offline archive.
1. Update these Dockerfiles:
1. **Update the `:latest` and `:archives` Docker images:**
- `dockerfiles/Dockerfile.archives`: Add the latest version to the top of the list.
- `Dockerfile.master`: Remove the oldest version, and add the newest version to the
top of the list.
The following two Dockerfiles need to be updated:
1. `dockerfiles/Dockerfile.archives` - Add the latest version at the top of
the list.
1. `Dockerfile.master` - Rotate the versions (oldest gets removed and latest
is added at the top of the list).
1. In the end, there should be four files in total that have changed.
Commit and push to create the merge request using the "Release" template:
1. Commit and push to create the merge request. For example:
```shell
git add content/ Dockerfile.master dockerfiles/Dockerfile.archives
git commit -m "Release 12.0"
git push origin release-12-0
git commit -m "Release 13.9"
git push origin release-13-9
```
## 4. Update the dropdown for all online versions
The versions dropdown is in a way "hardcoded". When the site is built, it looks
at the contents of `content/_data/versions.yaml` and based on that, the dropdown
is populated. Older branches have different content, which means the
dropdown list is one or more releases behind. Remember that the new changes of
the dropdown are included in the unmerged `release-X-Y` branch.
Do not merge the release merge request yet.
The content of `content/_data/versions.yaml` needs to change for all online
versions (stable branches `X.Y` of the `gitlab-docs` project):
## Update dropdown for online versions
1. Run the Rake task that creates all the respective merge requests needed to
update the dropdowns. Set these to automatically be merged when their
pipelines succeed:
To update`content/_data/versions.yaml` for all online versions (stable branches `X.Y` of the
`gitlab-docs` project):
NOTE:
The `release-X-Y` branch needs to be present locally,
and you need to have switched to it, otherwise the Rake task fails.
1. Run the Rake task that creates all of the necessary merge requests to update the dropdowns. For
example, for the 13.9 release:
```shell
git checkout release-X-Y
git checkout release-13-9
./bin/rake release:dropdowns
```
1. [Visit the merge requests page](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?label_name%5B%5D=release)
to check that their pipelines pass, and once all are merged, proceed to the
following and final step.
These merge requests are set to automatically merge.
NOTE:
In case a pipeline fails, see [troubleshooting](#troubleshooting).
1. [Visit the merge requests page](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?label_name%5B%5D=release)
to check that their pipelines pass. After all MRs are merged, proceed to the following and final
step.
## 5. Merge the release merge request
## Merge release merge request and run Docker image builds
The dropdown merge requests should have now been merged into their respective
version (stable `X.Y` branch), which triggers another pipeline. At this point,
you need to only babysit the pipelines and make sure they don't fail:
The merge requests for the dropdowns should now all be merged into their respective stable branches.
Each merge triggers a new pipeline for each stable branch. Wait for the stable branch pipelines to
complete, then:
1. Check the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipelines)
and make sure all stable branches have green pipelines.
1. After all the pipelines of the online versions succeed, merge the release merge request.
1. After all the pipelines succeed, merge the [release merge request](#create-release-merge-request).
1. Finally, run the
[`Build docker images weekly` pipeline](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules)
that builds the `:latest` and `:archives` Docker images.
Once the scheduled pipeline succeeds, the docs site is deployed with all
new versions online.
## Troubleshooting
Releasing a new version is a long process that involves many moving parts.
### `test_internal_links_and_anchors` failing on dropdown merge requests
WARNING:
We now pin versions in the `.gitlab-ci.yml` of the respective branch,
so the steps below are deprecated.
When [updating the dropdown for the stable versions](#4-update-the-dropdown-for-all-online-versions),
there may be cases where some links might fail. The process of how the
dropdown MRs are created have a caveat, and that is that the tests run by
pulling the master branches of all products, instead of the respective stable
ones.
In a real world scenario, the [Update 12.2 dropdown to match that of 12.4](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/604)
merge request failed because of the [`test_internal_links_and_anchors` test](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042431).
This happened because there has been a rename of a product (`gitlab-monitor` to `gitlab-exporter`)
and the old name was still referenced in the 12.2 docs. If the respective stable
branches for 12.2 were used, this wouldn't have failed, but as we can see from
the [`compile_dev` job](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/328042427),
the `master` branches were pulled.
To fix this, re-run the pipeline (`https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new`)
for the `update-12-2-for-release-12-4` branch, by including the following CI/CD variables:
- `BRANCH_CE` set to `12-2-stable`
- `BRANCH_EE` set to `12-2-stable-ee`
- `BRANCH_OMNIBUS` set to `12-2-stable`
- `BRANCH_RUNNER` set to `12-2-stable`
- `BRANCH_CHARTS` set to `2-2-stable`
This should make the MR pass.
As the last step in the scheduled pipeline, the documentation site deploys with all new versions.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7