From 7a5bf709e4118714bdefc488ad20a476ab796c10 Mon Sep 17 00:00:00 2001 From: Eduard Tudenhoefner Date: Fri, 3 Jun 2022 14:32:11 +0200 Subject: [PATCH 1/2] Update docs around how to prepare/release docs --- landing-page/content/common/how-to-release.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index fb3bb25ce..65612f6af 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 ``` ```text -I'm please to announce the release of Apache Iceberg ! +I'm pleased to announce the release of Apache Iceberg ! Apache Iceberg is an open table format for huge analytic datasets. Iceberg delivers high query performance for tables with tens of petabytes of data, @@ -264,23 +264,25 @@ 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. +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. 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. Adjust the commands accordingly if it is not the case. #### 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/` with a `_index.md` file. See the existing folders under `docs/versioned/releases` for more details. + +1. Create a new folder called `docs/releases/` with an `_index.md` file. See the existing folders under `docs/releases` for more details. #### iceberg-docs repository preparations -A PR needs to be published in `iceberg-docs` repository with the following changes: +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. Update the latest artifact links in the release notes page in `landing-page/content/common/release-notes.md` +5. Add release notes for the new release version in `landing-page/content/common/release-notes.md` #### Documentation update @@ -288,9 +290,7 @@ To start the release process, run the following steps in the `iceberg-docs` repo ```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 +cp -r ../iceberg/docs ../iceberg-docs/docs/content/docs ``` The resulted changes in `iceberg-docs` should be approved in a separate PR. @@ -301,7 +301,7 @@ In the `iceberg` repository, generate the javadoc for your release and copy it t ```shell ./gradlew refreshJavadoc rm -rf ../iceberg-docs/javadoc -cp site/docs/javadoc/ ../iceberg-docs/javadoc +cp -r site/docs/javadoc/ ../iceberg-docs/javadoc ``` This resulted changes in `iceberg-docs` should be approved in a separate PR. From 4ea18e8d3339a0ee2966ec7596e5ed5d6e3f9794 Mon Sep 17 00:00:00 2001 From: Samuel Redai <43911210+samredai@users.noreply.github.com> Date: Sun, 12 Jun 2022 23:45:33 -0700 Subject: [PATCH 2/2] Updating how to release documentation (#1) --- landing-page/content/common/how-to-release.md | 68 +++++++++++-------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 65612f6af..a0f64a239 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -263,42 +263,52 @@ 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. 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. -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: +A PR needs to be published in the `iceberg` repository with the following changes: 1. Create a new folder called `docs/releases/` with an `_index.md` file. See the existing folders under `docs/releases` for more details. -#### iceberg-docs repository preparations +#### Common documentation update -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. Update the latest artifact links in the release notes page in `landing-page/content/common/release-notes.md` -5. Add release notes for the new release version in `landing-page/content/common/release-notes.md` +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 +``` +3. Commit, push, and open a PR against the `iceberg-docs` repo (`` -> `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 +cd ../iceberg-docs +git checkout -b +git push --set-upstream apache +``` +2. Copy the versioned docs from the `iceberg` repo into the `iceberg-docs` repo ```shell -rm -rf ../iceberg-docs/docs/content/docs cp -r ../iceberg/docs ../iceberg-docs/docs/content/docs ``` - -The resulted changes in `iceberg-docs` should be approved in a separate PR. +3. Commit the changes and open a PR against the `` 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 -r site/docs/javadoc/ ../iceberg-docs/javadoc @@ -306,23 +316,21 @@ cp -r site/docs/javadoc/ ../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`