From 449e4dacbaa6b88775e1354bb639149ce5383089 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 23 Jan 2024 17:54:18 +0100 Subject: Document the use of the BRANCH_ variable --- .gitlab-ci.yml | 10 ++++++++++ doc/development.md | 2 ++ doc/raketasks.md | 47 +++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 57 insertions(+), 2 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 1a21c8b6..b771f94e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -27,6 +27,16 @@ variables: MARKDOWNLINT2_VERSION: '0.12.1' # Version also set in package.json RUBY_VERSION: '3.2.3' ASDF_VERSION: '0.14.0' + ## -------------------------------------------------------------------------- + ## Uncomment any of the following variables if you want to build the site + ## using another upstream branch. See + ## https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clone-an-upstream-branch-other-than-the-default + ## -------------------------------------------------------------------------- + # BRANCH_EE: + # BRANCH_OMNIBUS: + # BRANCH_RUNNER: + # BRANCH_CHARTS: + # BRANCH_OPERATOR: # # workflow:rules to prevent duplicate pipelines when pushing to a branch with an open MR. diff --git a/doc/development.md b/doc/development.md index d9809d0a..d83ded88 100644 --- a/doc/development.md +++ b/doc/development.md @@ -196,6 +196,7 @@ To add an additional set of product documentation to f branch at all, you can omit this and the default branch will be always pulled. 1. Edit ['lib/edit_on_gitlab.rb'](../lib/edit_on_gitlab.rb) and add the product and its attributes to the `PRODUCT_REPOS` object, then add 1-2 test cases in [`spec/lib/helpers/edit_on_gitlab_spec.rb`](../spec/lib/helpers/edit_on_gitlab_spec.rb). +1. Edit [`.gitlab-ci.yml`](../.gitlab-ci.yml) and add the new `BRANCH_` variable under `variables`. For example, if the slug is named `foo`, the variable should be named `BRANCH_FOO`. 1. Edit [`.test.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/test.gitlab-ci.yml) and add the new product to the following tests, following the same pattern as existing products: - `test_global_nav_links` @@ -214,6 +215,7 @@ To add an additional set of product documentation to f - Add the new product to the list in [`doc/index.md`](../doc/index.md). - Add the new product to the diagram in [`doc/architecture.md`](../doc/architecture.md). + - Add the new product environment variable (`BRANCH_`) in [`doc/raketasks.md`](../doc/raketasks.md#clone-an-upstream-branch-other-than-the-default). 1. Add new whitespace test target to `markdownlint-whitespace-tests-gitlab` in `Makefile`. diff --git a/doc/raketasks.md b/doc/raketasks.md index c66a96c8..8a166dd4 100644 --- a/doc/raketasks.md +++ b/doc/raketasks.md @@ -37,6 +37,47 @@ Available environment variables: set in a pipeline since `CI` is set to `true` by default, and it makes sure we're not reusing an old version of the docs in case we land on a runner that already has a docs build. +- `BRANCH_`: if you want to clone an upstream branch + [other than the default](#clone-an-upstream-branch-other-than-the-default). + +### Clone an upstream branch other than the default + +The +[`clone_repositories` task](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fd64306b4ba4efd4081ac96e7cf69756fef2ce2f/lib/tasks/build_site.rake#L10) +clones the +[default branch](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fd64306b4ba4efd4081ac96e7cf69756fef2ce2f/lib/tasks/task_helpers.rb#L41) +of an upstream project if the `BRANCH_` variable is not set. + +If you want to use another branch, you can use the `BRANCH_` environment +variable for the following products: + +- `BRANCH_EE` for `gitlab-org/gitlab` +- `BRANCH_OMNIBUS` for `gitlab-org/omnibus-gitlab` +- `BRANCH_RUNNER` for `gitlab-org/gitlab-runner` +- `BRANCH_CHARTS` for `gitlab-org/charts/gitlab` +- `BRANCH_OPERATOR` for `gitlab-org/cloud-native/gitlab-operator` + +You can use those variables either locally or in a merge request: + +- The most common scenario is when you'd like to deploy a `gitlab-docs` + review app using an upstream branch that contains changes pertinent to that + `gitlab-docs` merge request: + + 1. In a `gitlab-docs` merge request, edit the `variables` section of + [`.gitlab-ci.yml`](../.gitlab-ci.yml), adding the `BRANCH_` variable + you want to pull the respective upstream branch for. + 1. When you verify the merge request works the way you want, restore + `.gitlab-ci.yml` the way it was. + +- You can also use it locally by setting the variable before running the Rake task, + for example: + + ```shell + BRANCH_EE=update-tier-badges bundle exec rake clone_repositories + ``` + + The above example fetches the default branches for all the upstream projects + except for `gitlab-org/gitlab`, which is set to `update-tier-badges`. ### Usage of `clone_repositories` in an upstream review app @@ -49,8 +90,10 @@ The following process describes how this works: in an upstream project. 1. The following variables are [set and passed](https://gitlab.com/gitlab-org/gitlab/-/blob/53233de16cafa6544ebe7bfbe41fd65e95645c8e/scripts/trigger-build.rb#L239-337) on the `gitlab-docs` pipeline: - - `BRANCH_` is set to the upstream project's branch name, where - `` is one of `ee`, `omnibus`, `runner`, `charts`, `operator`. + - `BRANCH_` is set to the upstream project's branch name, where + `` is one of `ee`, `omnibus`, `runner`, `charts`, `operator`. With this + variable set up, when the docs site is built, it fetches the + [respective upstream branch](#clone-an-upstream-branch-other-than-the-default). - `CI_PIPELINE_SOURCE` is set to `trigger`. 1. A minimal pipeline is run in `gitlab-docs` with two jobs: - `compile_upstream_review_app`: builds the site by using the `clone_repositories` -- cgit v1.2.3