This is an automated email from the ASF dual-hosted git repository.
pingtimeout pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 211ba3c58 Describe the documentation steps of the release process
(#3476)
211ba3c58 is described below
commit 211ba3c587be17f8034f069ca1c19b80a4d27dbd
Author: Pierre Laporte <[email protected]>
AuthorDate: Mon Feb 16 16:46:04 2026 +0100
Describe the documentation steps of the release process (#3476)
These steps have not been automated (and might not be automatable). But
more importantly, they were not clearly defined. This PR is an attempt
at sharing knowledge following the lessons learned during 1.3.0 release.
---
.../release-guides/manual-release-guide.md | 75 ++++++++++++++++++++--
.../release-guides/semi-automated-release-guide.md | 74 +++++++++++++++++++--
2 files changed, 140 insertions(+), 9 deletions(-)
diff --git a/site/content/community/release-guides/manual-release-guide.md
b/site/content/community/release-guides/manual-release-guide.md
index 4998aca75..bdfd03ceb 100644
--- a/site/content/community/release-guides/manual-release-guide.md
+++ b/site/content/community/release-guides/manual-release-guide.md
@@ -465,11 +465,76 @@ You can now publish Docker images on DockerHub:
./gradlew :polaris-admin:assemble :polaris-admin:quarkusAppPartsBuild --rerun
-Dquarkus.container-image.build=true -Dquarkus.container-image.push=true
-Dquarkus.docker.buildx.platform="linux/amd64,linux/arm64"
-Dquarkus.container-image.tag=x.y.z
```
-### Publishing docs
-1. Open a PR against branch
[`versioned-docs`](https://github.com/apache/polaris/tree/versioned-docs) to
publish the documentation
-2. Open a PR against the `main` branch to update website
- - Add download links and release notes in [Download
page](https://github.com/apache/polaris/blob/main/site/content/downloads/_index.md)
- - Add the release in the [website
menu](https://github.com/apache/polaris/blob/main/site/hugo.yaml)
+### Upload the documentation
+Now that the release artifacts have been published, the next step is to
publish the associated documentation on the website.
+
+First, checkout the release tag:
+
+```
+git checkout apache-polaris-[major].[minor].[patch]-incubating
+```
+
+Set up a worktree for the versioned docs and create a new branch:
+
+```
+site/bin/checkout-releases.sh
+cd site/content/releases
+git checkout -b versioned-docs-[major].[minor].[patch]
+mkdir [major].[minor].[patch]
+```
+
+Copy the documentation from the release tag:
+
+```
+cp -r ../../content/in-dev/unreleased/* [major].[minor].[patch]/
+```
+
+Edit the file `[major].[minor].[patch]/_index.md` and perform the following
modifications:
+* Change the title from `In Development` to `[major].[minor].[patch]`.
+* Remove the `alert warning` block that warns that the documentation is for
the main branch.
+
+Commit and push to your fork:
+
+```
+git add .
+git commit -m "Add documentation for [major].[minor].[patch]"
+git push <your-fork> versioned-docs-[major].[minor].[patch]
+```
+
+Clean up the worktree:
+
+```
+cd ../../..
+site/bin/remove-releases.sh
+```
+
+Then open a PR against the `versioned-docs` branch with your changes.
+
+### Update the download links on the website
+The final step is to update the "Download" page on Polaris website with links
to the newly released artifacts. Checkout the `main` branch locally.
+
+```
+git checkout -b main-site-download-links-[major].[minor].[patch] main
+```
+
+Edit the file `site/content/downloads/_index.md` and add a new section for the
release. The section should contain the following information:
+
+* A table with links to each of the artifacts, its PGP signature and
associated checksum. All links in this section MUST point to
`https://dlcdn.apache.org/` or `https://downloads.apache.org/`.
+* The release date.
+* A paragraph with the release notes.
+
+Then update the section of the previous release so that it references
`https://archive.apache.org` instead of `https://dlcdn.apache.org/` and
`https://downloads.apache.org/`.
+
+Finally, edit the file `site/hugo.yaml`. Add a new bullet point under
`active_releases` for the new release. Also add a menu item under `menu.main`,
**after** the `In Development` menu item, with have the following format:
+
+```
+ - name: "[major].[minor].[patch]"
+ url: "/releases/[major].[minor].[patch]/"
+ parent: "doc"
+ weight: [previous release weight - 1]
+```
+
+Then open a PR against the `main` branch with your changes.
### Announcing the release
To announce the release, wait until Maven Central has mirrored the artifacts.
diff --git
a/site/content/community/release-guides/semi-automated-release-guide.md
b/site/content/community/release-guides/semi-automated-release-guide.md
index 3b5748341..9090dba96 100644
--- a/site/content/community/release-guides/semi-automated-release-guide.md
+++ b/site/content/community/release-guides/semi-automated-release-guide.md
@@ -301,7 +301,73 @@ This workflow can only be run from the
`release/[major].[minor].x` branch for wh
## Publish docs
These steps have not been automated yet.
-1. Open a PR against branch
[`versioned-docs`](https://github.com/apache/polaris/tree/versioned-docs) to
publish the documentation
-2. Open a PR against the `main` branch to update website
- - Add download links and release notes in [Download
page](https://github.com/apache/polaris/blob/main/site/content/downloads/_index.md)
- - Add the release in the [website
menu](https://github.com/apache/polaris/blob/main/site/hugo.yaml)
+### Upload the documentation
+Now that the release artifacts have been published, the next step is to
publish the associated documentation on the website.
+
+First, checkout the release tag:
+
+```
+git checkout apache-polaris-[major].[minor].[patch]-incubating
+```
+
+Set up a worktree for the versioned docs and create a new branch:
+
+```
+site/bin/checkout-releases.sh
+cd site/content/releases
+git checkout -b versioned-docs-[major].[minor].[patch]
+mkdir [major].[minor].[patch]
+```
+
+Copy the documentation from the release tag:
+
+```
+cp -r ../../content/in-dev/unreleased/* [major].[minor].[patch]/
+```
+
+Edit the file `[major].[minor].[patch]/_index.md` and perform the following
modifications:
+* Change the title from `In Development` to `[major].[minor].[patch]`.
+* Remove the `alert warning` block that warns that the documentation is for
the main branch.
+
+Commit and push to your fork:
+
+```
+git add .
+git commit -m "Add documentation for [major].[minor].[patch]"
+git push <your-fork> versioned-docs-[major].[minor].[patch]
+```
+
+Clean up the worktree:
+
+```
+cd ../../..
+site/bin/remove-releases.sh
+```
+
+Then open a PR against the `versioned-docs` branch with your changes.
+
+### Update the download links on the website
+The final step is to update the "Download" page on Polaris website with links
to the newly released artifacts. Checkout the `main` branch locally.
+
+```
+git checkout -b main-site-download-links-[major].[minor].[patch] main
+```
+
+Edit the file `site/content/downloads/_index.md` and add a new section for the
release. The section should contain the following information:
+
+* A table with links to each of the artifacts, its PGP signature and
associated checksum. All links in this section MUST point to
`https://dlcdn.apache.org/` or `https://downloads.apache.org/`.
+* The release date.
+* A paragraph with the release notes.
+
+Then update the section of the previous release so that it references
`https://archive.apache.org` instead of `https://dlcdn.apache.org/` and
`https://downloads.apache.org/`.
+
+Finally, edit the file `site/hugo.yaml`. Add a new bullet point under
`active_releases` for the new release. Also add a menu item under `menu.main`,
**after** the `In Development` menu item, with have the following format:
+
+```
+ - name: "[major].[minor].[patch]"
+ url: "/releases/[major].[minor].[patch]/"
+ parent: "doc"
+ weight: [previous release weight - 1]
+```
+
+Then open a PR against the `main` branch with your changes.
