[iceberg-docs] branch main updated: Docs: Update docs around how to prepare/release docs (#87)

[ru...@apache.org]

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 <ed...@dremio.com>
AuthorDate: Wed Jun 15 15:54:32 2022 +0200

    Docs: Update docs around how to prepare/release docs (#87)
    
    
    Co-authored-by: Samuel Redai <43...@users.noreply.github.com>
---
 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`