From 8d9ecb54468ea15c573974a5bf2146834c310093 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Wed, 13 May 2026 19:20:29 +0530 Subject: [PATCH] docs: comprehensive README with release workflow and CI explanation Rewrite docs/README.md to fully document: - Cutting a new release (display_version, auto-detection) - How publishing works with detailed job-by-job explanation - How the check job gates build/deploy via GITHUB_OUTPUT - That docs are built from the release branch directly (no docs branch or tag) - GitHub Pages configuration requirements Co-Authored-By: Claude Opus 4.6 --- docs/README.md | 83 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 58 insertions(+), 25 deletions(-) diff --git a/docs/README.md b/docs/README.md index cd1f6d387..947f7e7a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,8 +8,8 @@ This directory contains the [Antora](https://antora.org/)-based documentation fo | Branch | Purpose | |--------|---------| -| `main` | Development branch. All new doc work starts here. | -| `release-X.Y` | Release branches (e.g., `release-0.1`). The **latest** release branch is the source for the published site. | +| `main` | Development branch. All new doc work starts here. PRs to `main` validate the build but do not publish. | +| `release-X.Y` | Release branches (e.g., `release-0.1`). The **latest** release branch is the source for the published site. Docs are built and deployed directly from this branch — there is no separate `docs` branch or tag involved. | ## Contributing documentation changes @@ -21,7 +21,7 @@ This directory contains the [Antora](https://antora.org/)-based documentation fo ``` 2. Edit files under `docs/modules/ROOT/pages/`. 3. Build locally to verify (see [Local build](#local-build) below). -4. Open a PR against `main`. CI validates the Antora build. +4. Open a PR against `main`. CI runs the `validate` job to check the Antora build. 5. Merge the PR. Merging to `main` does **not** update the live site. @@ -39,50 +39,82 @@ git push upstream release-0.1 Or open a separate PR targeting the release branch directly. -Once the push lands on the latest release branch, the live site updates automatically within a few minutes. +Once the push lands on the latest release branch, CI automatically builds and deploys the site. The live site updates within a few minutes. -### When a new release is cut +## Cutting a new release -When a new release branch is created (e.g., `release-0.2`): +When creating a new release branch (e.g., `release-0.2`): -- The new branch automatically becomes the publishing source. -- Pushes to older release branches (e.g., `release-0.1`) stop publishing. -- No configuration or variable updates are needed. +1. **Create the branch** from `main` as usual. +2. **Update `display_version`** in `docs/antora.yml` on the new release branch: + ```yaml + display_version: '0.2' + ``` + This controls the version number shown in the toolbar next to "Edit this Page". +3. **No CI or GitHub settings changes are needed.** The workflow automatically detects the latest `release-*` branch by semver sort. Once `release-0.2` exists, it becomes the publishing source and pushes to `release-0.1` stop publishing. ## How publishing works -Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). The workflow has four jobs: +Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). The docs source is built directly from the release branch that triggered the workflow — no intermediate branch or tag is involved. + +### Workflow triggers + +The workflow runs on two events: +- **Pull request to `main`** (only if files in `docs/` or `antora-playbook.yml` changed) — validates the build. +- **Push to any `release-*` branch** — checks if this is the latest release, and if so, builds and deploys. + +### Jobs + +There are four jobs. On a push to a release branch, they run in sequence: `check` → `build` → `deploy`. On a PR to `main`, only `validate` runs. + +#### 1. `check` (push to `release-*` only) -### 1. `check` job (runs on push to any `release-*` branch) +Determines whether the pushed branch is the latest release branch. -- Queries all remote `release-*` branches using `git ls-remote`. -- Sorts them by semver to find the latest (e.g., `release-0.2` > `release-0.1`). -- Outputs `is-latest=true` if the pushed branch is the latest, `false` otherwise. +- Runs `git ls-remote` to list all `release-*` branches on the remote. +- Sorts them by semver (e.g., `release-0.2` > `release-0.1`). +- Writes the result to `$GITHUB_OUTPUT` so downstream jobs can read it. +- Sets `is-latest=true` if the pushed branch matches, `false` otherwise. -### 2. `validate` job (runs on PRs to `main`) +**How the gating works:** The `check` job declares an `outputs` section that exposes `is-latest`. The `build` job has `needs: check` and an `if` condition that reads `needs.check.outputs.is-latest == 'true'`. If the check says `false`, `build` is skipped, and since `deploy` depends on `build`, it is also skipped. This is standard GitHub Actions job chaining — one job writes to `$GITHUB_OUTPUT`, the next reads it via `needs..outputs.`. +#### 2. `validate` (PRs to `main` only) + +- Checks out the PR branch. - Builds the site with Antora to verify the docs compile without errors. -- Does **not** deploy. This is a build-only check. +- Does **not** upload artifacts or deploy. This is a build-only check. -### 3. `build` job (runs after `check`, only if `is-latest` is `true`) +#### 3. `build` (after `check`, only if `is-latest` is `true`) -- Checks out the release branch. +- Checks out the release branch (the same branch that triggered the workflow). - Installs Antora 3.1 and the Lunr search extension. -- Runs `antora --fetch antora-playbook.yml` to build the site. -- Creates a `.nojekyll` file (required for GitHub Pages to serve Antora assets). +- Runs `antora --fetch antora-playbook.yml` to build the site from the docs source on this branch. +- Creates a `.nojekyll` file (required for GitHub Pages to serve Antora's `_/`-prefixed asset directories). - Uploads the build output as a GitHub Pages artifact. -### 4. `deploy` job (runs after `build` succeeds) +**Key point:** The build uses the docs content from the release branch itself. There is no separate `docs` branch or `docs` tag. Whatever is on the release branch at the time of the push is what gets published. + +#### 4. `deploy` (after `build` succeeds) + +- Deploys the Pages artifact to the `github-pages` environment. +- The live site updates at https://redhat-appstudio.github.io/tsf-cli/. -- Deploys the artifact to GitHub Pages. +### Flow diagram ``` -PR to main ──> validate (build-only check, no deploy) +PR to main ──> validate (build-only, no deploy) -Push to release-* ──> check ──> is this the latest? ──yes──> build ──> deploy +Push to release-* ──> check ──> is this the latest? ──yes──> build (from release branch) ──> deploy ──no──> skip (all remaining jobs skipped) ``` +### GitHub Pages configuration + +These settings are in the GitHub repo settings and do not need to change per release: + +- **Source** (Settings → Pages): GitHub Actions (not "Deploy from a branch"). +- **Deployment branches** (Settings → Environments → github-pages): `release-*` must be an allowed branch pattern. + ## Local build From the `docs/` directory: @@ -121,6 +153,7 @@ docs/ ├── header-content.hbs # Navbar with Home link, Raise Issue, search ├── head-styles.hbs # CSS includes (site.css + main.css) ├── footer-content.hbs # Footer with GitHub and issue links + ├── toolbar.hbs # Version display + Edit this Page link └── pagination.hbs # Prev/next page navigation antora-playbook.yml # Antora playbook (lives at repo root, not in docs/) @@ -136,7 +169,7 @@ Product-specific attributes are defined in `antora.yml` and available in all pag | `{TSFName}` | Trusted Software Factory | Full product name | | `{TSFShortName}` | TSF | Short product name | | `{TSFCli}` | tsf | CLI tool name | -| `{TSFInstallerImage}` | quay.io/redhat-ads/tsf-cli:unstable | Installer container image | +| `{TSFInstallerImage}` | quay.io/redhat-ads/tsf-cli:latest | Installer container image | | `{OCPName}` | OpenShift Container Platform | Full OCP name | | `{OCPShortName}` | OCP | Short OCP name | | `{OCPVersion}` | 4.20 | Target OCP version |