This is an automated email from the ASF dual-hosted git repository. royteeuwen pushed a commit to branch docs/release-management-finalize-website in repository https://gitbox.apache.org/repos/asf/sling-site.git
commit a5d6b7f3283ce0dfd76bd6299fd936457cc598b4 Author: Roy Teeuwen <[email protected]> AuthorDate: Tue Aug 4 20:23:25 2026 +0200 Release docs: finalize now updates the website The CLI's finalize command updates the releases list and the downloads page as its last step, so document that rather than telling the release manager to do it afterwards, and describe how downloads entries are matched (artifact id, same major version only). The news page stays manual, via update-news. Also correct the manual downloads instructions: the page needs updating for every release, not only for new modules, and it lists only the most recent major version of a module even when older ones are still distributed. --- .../development/release-management.md | 44 +++++++++++++++++----- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/src/main/jbake/content/documentation/development/release-management.md b/src/main/jbake/content/documentation/development/release-management.md index a78a2f9bc..61ffd0b05 100644 --- a/src/main/jbake/content/documentation/development/release-management.md +++ b/src/main/jbake/content/documentation/development/release-management.md @@ -63,8 +63,9 @@ Everything else is configured in the [Sling parent POM](https://github.com/apach The [Sling Committer CLI](https://github.com/apache/sling-org-apache-sling-committer-cli) is a Docker image that drives a release end-to-end: it closes the staging repository, verifies signatures, checksums and CI status, sends the `[VOTE]` and `[RESULT]` emails, promotes to Maven Central, updates -`dist.apache.org`, JIRA and the Apache Reporter. It performs exactly the steps documented in the -manual process below, so it is the recommended way to run a release. +`dist.apache.org`, JIRA and the Apache Reporter, and updates the releases and downloads pages on this +website. It performs exactly the steps documented in the manual process below, so it is the +recommended way to run a release. ### One-time setup @@ -131,15 +132,35 @@ version (see [Canceling the Release](#canceling-the-release)): `finalize` runs, in order: update `dist.apache.org` (only when you are a PMC member — the previous version to remove is detected automatically), promote to Maven Central, create the next JIRA version -and move unresolved issues, mark the JIRA version as released, and update the Apache Reporter. The -dist upload runs first because it is the only step that needs the staging repository, which promoting -to Maven Central drops. A JIRA pre-flight check runs before any of these irreversible steps. - -Afterwards update the website (releases / downloads / news) as described in -[Promoting the Release](#promoting-the-release); the website diff can be generated with: +and move unresolved issues, mark the JIRA version as released, update the Apache Reporter, and update +the website. The dist upload runs first because it is the only step that needs the staging repository, +which promoting to Maven Central drops. A JIRA pre-flight check runs before any of these irreversible +steps. + +The website step adds the release to [releases](/releases.html) and bumps the matching entries on the +[downloads](/downloads.cgi) page, then commits and pushes to `sling-site`. Downloads entries are +matched on the *artifact id* rather than on the module's display name, because the two often differ +(*Tracer* is listed as *Log Tracer*) and one release can own several entries. Only entries on the same +major version are updated, so a maintenance release of an older line (for example Resource Resolver +1.12.x while the page lists 2.x) never downgrades the page. If a module has no downloads entry at all +— typically a brand new module — that is reported so it can be added by hand. + +To review the website changes without pushing them, run the step on its own; like every command it +defaults to `DRY_RUN` and only prints the diff: $cli release update-local-site -r <REPO_ID> +The [news](/news.html) page is deliberately *not* updated by `finalize`, since only releases that +warrant an announcement belong there. For those, run: + + $cli release update-news --release "Apache Sling ABC X.Y.Z" \ + --link /documentation/bundles/abc.html -x AUTO + +Every step after the dist upload is independent of the staging repository, so if `finalize` fails part +way through you can re-run it. Before promotion resume with `-r <REPO_ID>`; afterwards the staging +repository is gone, so resume with `--release "Apache Sling ABC X.Y.Z"`. Completed steps are detected +and skipped. + The sections below document the same steps performed manually. They are useful for understanding what the CLI does and as a fallback when it cannot be used. @@ -309,10 +330,13 @@ If the vote passes: 2. Once the release is promoted click on *Repositories* on the left, select the *Releases* repository and validate that your artifacts are all there. 3. Following the release promotion you will receive an email from the 'Apache Reporter Service'. Follow the link and add the release data, as it used by the PMC chair to prepare board reports. To simplify this task you can use the script from [https://github.com/apache/sling-tooling-release/blob/master/update_reporter.sh](https://github.com/apache/sling-tooling-release/blob/master/update_reporter.sh). Alternatively you can add the release data directly via <https://reporter.apache.org/ad [...] 2. Update the releases section on the website at [releases](/releases.html). -3. For new modules, update the download page on the website at [downloads](/downloads.cgi) to point to the new release. For this you need to modify the [according Groovy Template](https://github.com/apache/sling-site/blob/master/src/main/jbake/templates/downloads.tpl). For existing modules the [renovate app](https://github.com/renovatebot/renovate/) will generate a pull request. The pull request must be manually merged. +3. Update the download page on the website at [downloads](/downloads.cgi) to point to the new release. For this you need to modify the [according Groovy Template](https://github.com/apache/sling-site/blob/master/src/main/jbake/templates/downloads.tpl), keeping in mind that the page lists only the most recent major version of a module even when older major versions are still distributed, and that a release may own several entries (one per artifact). So a maintenance release of an older ma [...] 4. If you think that this release is worth a news entry, update the website at [news](/news.html) -For the last two tasks, it's better to give the CDN some time to process the uploaded artifacts (15 minutes should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts. +Steps 2 and 3 are performed automatically by the Committer CLI's `finalize` command; step 4 is left to +you, via `release update-news`. See [Finalize](#4-finalize). + +For the last two tasks, it's better to give the CDN some time to process the uploaded artifacts (15 minutes should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts. Note that the website itself is only rebuilt and deployed some minutes after the change is pushed, which in practice already covers most of that delay. ### Quick update of artifacts in dist
