[GitHub] [iceberg-docs] RussellSpitzer commented on a diff in pull request #87: Update docs around how to prepare/release docs

[GitBox <gi...@apache.org>]

RussellSpitzer commented on code in PR #87:
URL: https://github.com/apache/iceberg-docs/pull/87#discussion_r895713368


##########
landing-page/content/common/how-to-release.md:
##########
@@ -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, simply rebase `latest` branch against `main`:

Review Comment:
   nit: avoid "simply"



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org