This is an automated email from the ASF dual-hosted git repository.
russellspitzer pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 3c3d40d Docs: Update docs around how to prepare/release docs (#87)
3c3d40d is described below
commit 3c3d40dd78edf98058f18e1c62967662fdf99c31
Author: Eduard Tudenhöfner <[email protected]>
AuthorDate: Wed Jun 15 15:54:32 2022 +0200
Docs: Update docs around how to prepare/release docs (#87)
Co-authored-by: Samuel Redai <[email protected]>
---
landing-page/content/common/how-to-release.md | 78 +++++++++++++++------------
1 file changed, 43 insertions(+), 35 deletions(-)
diff --git a/landing-page/content/common/how-to-release.md
b/landing-page/content/common/how-to-release.md
index fb3bb25..a0f64a2 100644
--- a/landing-page/content/common/how-to-release.md
+++ b/landing-page/content/common/how-to-release.md
@@ -247,7 +247,7 @@ To announce the release, wait until Maven central has
mirrored the Apache binari
[ANNOUNCE] Apache Iceberg release <VERSION>
```
```text
-I'm please to announce the release of Apache Iceberg <VERSION>!
+I'm pleased to announce the release of Apache Iceberg <VERSION>!
Apache Iceberg is an open table format for huge analytic datasets. Iceberg
delivers high query performance for tables with tens of petabytes of data,
@@ -263,66 +263,74 @@ Thanks to everyone for contributing!
### Documentation Release
-Documentation needs to be updated as a part of Iceberg release after a release
candidate is passed.
-The commands described below assume the `iceberg-docs` repository and
`iceberg` repository are in the same parent directory locally,
-and the release manager is executing commands in the `iceberg` repository.
-Adjust the commands accordingly if it is not the case.
+Documentation needs to be updated as a part of an Iceberg release after a
release candidate is passed.
+The commands described below assume you are in a directory containing a local
clone of the `iceberg-docs`
+repository and `iceberg` repository. Adjust the commands accordingly if it is
not the case. Note that all
+changes in `iceberg` need to happen against the `master` branch and changes in
`iceberg-docs` need to happen
+against the `main` branch.
#### iceberg repository preparations
-A PR needs to be published in `iceberg` repository with the following changes:
-1. Mark the current latest release notes to past releases
-2. Update the latest artifact links in the release notes page
-3. Add release notes for the new release version
-2. Create new folder called `docs/versioned/releases/<VERSION NUMBER>` with a
`_index.md` file. See the existing folders under `docs/versioned/releases` for
more details.
+A PR needs to be published in the `iceberg` repository with the following
changes:
-#### iceberg-docs repository preparations
+1. Create a new folder called `docs/releases/<VERSION NUMBER>` with an
`_index.md` file. See the existing folders under `docs/releases` for more
details.
-A PR needs to be published in `iceberg-docs` repository with the following
changes:
-1. Update variable `latestVersions.iceberg` to the new release version in
`landing-page/config.toml`
-2. Update variable `latestVersions.iceberg` to the new release version in
`docs/config.toml`
+#### Common documentation update
+
+1. To start the release process, run the following steps in the `iceberg-docs`
repository to copy docs over:
+```shell
+cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/
+```
+2. Change into the `iceberg-docs` repository and create a branch.
+```shell
+cd ../iceberg-docs
+git checkout -b <BRANCH NAME>
+```
+3. Commit, push, and open a PR against the `iceberg-docs` repo (`<BRANCH
NAME>` -> `main`)
-#### Documentation update
+#### Versioned documentation update
-To start the release process, run the following steps in the `iceberg-docs`
repository to copy docs over:
+Once the common docs changes have been merged into `main`, the next step is to
update the versioned docs.
+1. In the `iceberg-docs` repository, cut a new branch using the version number
as the branch name
```shell
-rm -rf ../iceberg-docs/docs/content/docs
-rm -rf ../iceberg-docs/landing-page/content/common
-cp -r docs/versioned ../iceberg-docs/docs/content/docs
-cp -r docs/common ../iceberg-docs/landing-page/content/common
+cd ../iceberg-docs
+git checkout -b <VERSION>
+git push --set-upstream apache <VERSION>
```
-
-The resulted changes in `iceberg-docs` should be approved in a separate PR.
+2. Copy the versioned docs from the `iceberg` repo into the `iceberg-docs` repo
+```shell
+cp -r ../iceberg/docs ../iceberg-docs/docs/content/docs
+```
+3. Commit the changes and open a PR against the `<VERSION>` branch in the
`iceberg-docs` repo
#### Javadoc update
In the `iceberg` repository, generate the javadoc for your release and copy it
to the `javadoc` folder in `iceberg-docs` repo:
```shell
+cd ../iceberg
./gradlew refreshJavadoc
rm -rf ../iceberg-docs/javadoc
-cp site/docs/javadoc/<VERSION NUMBER> ../iceberg-docs/javadoc
+cp -r site/docs/javadoc/<VERSION NUMBER> ../iceberg-docs/javadoc
```
This resulted changes in `iceberg-docs` should be approved in a separate PR.
-#### Cut a new version branch
-
-Once completed, go to the `iceberg-docs` repository to cut a new branch using
the version number as the branch name.
-For example, to cut a new versioned doc for release `0.13.0`:
-
-```shell
-git checkout -b 0.13.0
-git push --set-upstream apache 0.13.0
-```
-
#### Update the latest branch
-The last step is to point the `latest` branch to the latest version.
-Because `main` is currently the same as the version branch, simply rebase
`latest` branch against `main`:
+Since `main` is currently the same as the version branch, one needs to rebase
`latest` branch against `main`:
```shell
git checkout latest
git rebase main
git push apache latest
```
+
+#### Set latest version in iceberg-docs repo
+
+The last step is to update the `main` branch in `iceberg-docs` to set the
latest version.
+A PR needs to be published in the `iceberg-docs` repository with the following
changes:
+1. Update variable `latestVersions.iceberg` to the new release version in
`landing-page/config.toml`
+2. Update variable `latestVersions.iceberg` to the new release version in
`docs/config.toml`
+3. Mark the current latest release notes to past releases under
`landing-page/content/common/release-notes.md`
+4. Add release notes for the new release version in
`landing-page/content/common/release-notes.md`
