diff options
Diffstat (limited to 'doc/development/documentation/site_architecture/release_process.md')
| -rw-r--r-- | doc/development/documentation/site_architecture/release_process.md | 228 |
1 files changed, 101 insertions, 127 deletions
diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index ba5363dbb71..7bdf3fbdcf8 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -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 environment 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. |