From 241f1765fd208bb20f7fcda301bfd0df766b8fcc Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Tue, 21 Mar 2023 14:46:00 -0700 Subject: [PATCH 1/9] Update how to release instructions with more details --- landing-page/content/common/how-to-release.md | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 0148f168a..374ce744c 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -220,6 +220,8 @@ Therefore, the release candidate is passed/rejected. ### Finishing the release +#### Apache release + After the release vote has passed, you need to release the last candidate's artifacts. First, copy the source release directory to releases: @@ -235,13 +237,40 @@ svn add apache-iceberg- svn ci -m 'Iceberg: Add release ' ``` +#### GitHub release + Next, add a release tag to the git repository based on the passing candidate tag: ```bash git tag -am 'Release Apache Iceberg ' apache-iceberg- apache-iceberg--rcN +git push apache apache-iceberg- +``` + +Then create a new GitHub release in https://github.com/apache/iceberg/releases from the release version tag. + +Next, clean up each RC tag with: + +```bash +git push --delete apache apache-iceberg--rcN ``` -Then release the candidate repository in [Nexus](https://repository.apache.org/#stagingRepositories). +For each major or minor version release, +publish the release branch with a `.x` in the end. +For example, for 1.2.0 release we do: + +```bash +git checkout -b 1.2.x apache-iceberg-1.2.0 +git push apache 1.2.x +``` + +#### Maven release + +1. Go to [Nexus](https://repository.apache.org/) and log in +2. In the menu on the left, choose "Staging Repositories" +3. Select the Iceberg repository that was previously closed and passed vote +4. At the top, select "Release" and follow the instructions + +#### Announcement email To announce the release, wait until Maven central has mirrored the Apache binaries, then update the Iceberg site and send an announcement email: From 0e74ddc961b3f624c1f9107522f881b0417b24b8 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Tue, 21 Mar 2023 15:27:27 -0700 Subject: [PATCH 2/9] add set upstream --- landing-page/content/common/how-to-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 374ce744c..3687303fb 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -260,7 +260,7 @@ For example, for 1.2.0 release we do: ```bash git checkout -b 1.2.x apache-iceberg-1.2.0 -git push apache 1.2.x +git push --set-upstream apache 1.2.x ``` #### Maven release From d5479cc82f22dc877e65172cdcd99ff2a98a2ab2 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Wed, 22 Mar 2023 12:30:50 -0700 Subject: [PATCH 3/9] add other steps --- landing-page/content/common/how-to-release.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 3687303fb..3284c2330 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -292,6 +292,13 @@ Java artifacts are available from Maven Central. Thanks to everyone for contributing! ``` +#### Codebase updates + +There are a few places in the codebase that reference the latest Iceberg releases and need to be updated: +1. https://github.com/apache/iceberg/blob/master/.github/ISSUE_TEMPLATE/iceberg_bug_report.yml +2. https://github.com/apache/iceberg/blob/master/python/dev/Dockerfile +3. `oldVersion` in `revapi` in https://github.com/apache/iceberg/blob/master/build.gradle + ### Documentation Release Documentation needs to be updated as a part of an Iceberg release after a release candidate is passed. @@ -300,12 +307,6 @@ repository and `iceberg` repository. Adjust the commands accordingly if it is no 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 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. - #### Common documentation update 1. To start the release process, run the following steps in the `iceberg-docs` repository to copy docs over: From 7d428af759d42538e0291041153435e9e2bef01e Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Wed, 22 Mar 2023 13:02:47 -0700 Subject: [PATCH 4/9] add more details --- landing-page/content/common/how-to-release.md | 67 ++++++++++++------- 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 3284c2330..1d1456739 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -294,60 +294,79 @@ Thanks to everyone for contributing! #### Codebase updates -There are a few places in the codebase that reference the latest Iceberg releases and need to be updated: +There are a few places in the codebase that reference the latest Iceberg release version number and need to be updated: 1. https://github.com/apache/iceberg/blob/master/.github/ISSUE_TEMPLATE/iceberg_bug_report.yml 2. https://github.com/apache/iceberg/blob/master/python/dev/Dockerfile 3. `oldVersion` in `revapi` in https://github.com/apache/iceberg/blob/master/build.gradle -### Documentation Release +### Documentation release 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. -#### Common documentation update +#### Prerequisites -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/ +Similar to the `iceberg` repository, you also need to set up `https://github.com/apache/iceberg-docs.git` as a remote with name `apache`. + +The commands described below assume you have a directory structure of: + +```text +/some/path +├── iceberg +└── iceberg-docs ``` -2. Change into the `iceberg-docs` repository and create a branch. + +And you are: +1. in the `iceberg-docs` repository. +2. have `iceberg` repository on the specific version branch + +Adjust the commands below accordingly if it is not the case. + +#### Update specs + +Copy the latest format specifications to `landing-page/content/common`: + ```shell -cd ../iceberg-docs -git checkout -b +cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/ ``` -3. Commit, push, and open a PR against the `iceberg-docs` repo (`` -> `main`) -#### Versioned documentation update +Raise a PR with the specific changes against `main` branch and merge. + +#### Create version branch -Once the common docs changes have been merged into `main`, the next step is to update the versioned docs. +Create a branch with the specific version number: -1. In the `iceberg-docs` repository, cut a new branch using the version number as the branch name ```shell -cd ../iceberg-docs +# sync main to latest first git checkout -b git push --set-upstream apache ``` -2. Copy the versioned docs from the `iceberg` repo into the `iceberg-docs` repo + +#### Copy versioned documentations + +Copy the versioned docs into `docs/content` + ```shell rm -rf ../iceberg-docs/docs/content cp -r ../iceberg/docs ../iceberg-docs/docs/content ``` -3. Commit the changes and open a PR against the `` branch in the `iceberg-docs` repo -#### Javadoc update +Raise a PR with the specific changes against `` branch and merge. + +#### Copy versioned Javadoc + + + +In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder: -In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder in `iceberg-docs` repo: ```shell cd ../iceberg +echo "" > version.txt ./gradlew refreshJavadoc rm -rf ../iceberg-docs/javadoc -cp -r 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. +Raise a PR with the specific changes against `` branch and merge. #### Update the latest branch From 82bf745f2697954ca6acdc9257af63f67884fa5a Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Wed, 22 Mar 2023 13:12:55 -0700 Subject: [PATCH 5/9] update doc inst --- landing-page/content/common/how-to-release.md | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 1d1456739..f440b5c75 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -331,16 +331,6 @@ cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/ Raise a PR with the specific changes against `main` branch and merge. -#### Create version branch - -Create a branch with the specific version number: - -```shell -# sync main to latest first -git checkout -b -git push --set-upstream apache -``` - #### Copy versioned documentations Copy the versioned docs into `docs/content` @@ -354,8 +344,6 @@ Raise a PR with the specific changes against `` branch and merge. #### Copy versioned Javadoc - - In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder: ```shell @@ -368,6 +356,16 @@ cp -r site/docs/javadoc/ ../iceberg-docs/javadoc Raise a PR with the specific changes against `` branch and merge. +#### Create version branch + +Create a branch with the specific version number: + +```shell +# sync main to latest first +git checkout -b +git push --set-upstream apache +``` + #### Update the latest branch Since `main` is currently the same as the version branch, one needs to rebase `latest` branch against `main`: From 6a478513f8ab0e79efef134d6a128d1c36615c35 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Wed, 22 Mar 2023 14:12:11 -0700 Subject: [PATCH 6/9] fix more doc release inst --- landing-page/content/common/how-to-release.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index f440b5c75..b50d05ea7 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -340,7 +340,7 @@ rm -rf ../iceberg-docs/docs/content cp -r ../iceberg/docs ../iceberg-docs/docs/content ``` -Raise a PR with the specific changes against `` branch and merge. +Raise a PR with the specific changes against `main` branch and merge. #### Copy versioned Javadoc @@ -354,20 +354,40 @@ rm -rf ../iceberg-docs/javadoc cp -r site/docs/javadoc/ ../iceberg-docs/javadoc ``` -Raise a PR with the specific changes against `` branch and merge. +Raise a PR with the specific changes against `main` branch and merge. + +#### Set latest versions + +The following fields need to be updated: +1. in `landing-page/config.toml`: + - update `latestVersions.iceberg` + - add one new row in `versions` for the latest version +2. in `docs/config.toml`: + - update `latestVersions.iceberg` + - update `versions.nessie` (check to the version of `org.projectnessie.nessie:*` from [versions.props](https://github.com/apache/iceberg/blob/master/versions.props)) + - add one new row in `versions` for the latest version + +Raise a PR with the specific changes against `main` branch and merge. + +### update release notes + +In page `landing-page/content/common/release-notes.md`: +1. Mark the current latest release notes to past releases +2. Add release notes for the new release version + +Raise a PR with the specific changes against `main` branch and merge. #### Create version branch Create a branch with the specific version number: ```shell -# sync main to latest first git checkout -b git push --set-upstream apache ``` -#### Update the latest branch - +#### Update the `latest` branch + Since `main` is currently the same as the version branch, one needs to rebase `latest` branch against `main`: ```shell @@ -376,17 +396,6 @@ 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 and -`versions.nessie` to the version of `org.projectnessie.nessie:*` from [versions.props](https://github.com/apache/iceberg/blob/master/versions.props) 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` - - # How to Verify a Release Each Apache Iceberg release is validated by the community by holding a vote. A community release manager From 82307fc56afffe7841768fd76ef9c8f193fc483d Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Thu, 23 Mar 2023 09:59:46 -0700 Subject: [PATCH 7/9] reorder steps --- landing-page/content/common/how-to-release.md | 78 ++++++++++--------- 1 file changed, 40 insertions(+), 38 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index b50d05ea7..7779d32cd 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -269,41 +269,13 @@ git push --set-upstream apache 1.2.x 2. In the menu on the left, choose "Staging Repositories" 3. Select the Iceberg repository that was previously closed and passed vote 4. At the top, select "Release" and follow the instructions +5. Wait until Maven central has mirrored the Apache binaries and the new version shows up in [Maven Central](https://mvnrepository.com/artifact/org.apache.iceberg) (this typically takes 1-2 days) -#### Announcement email - -To announce the release, wait until Maven central has mirrored the Apache binaries, then update the Iceberg site and send an announcement email: - -```text -[ANNOUNCE] Apache Iceberg release -``` -```text -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, -along with atomic commits, concurrent writes, and SQL-compatible table -evolution. - -This release can be downloaded from: https://www.apache.org/dyn/closer.cgi/iceberg// - -Java artifacts are available from Maven Central. - -Thanks to everyone for contributing! -``` - -#### Codebase updates - -There are a few places in the codebase that reference the latest Iceberg release version number and need to be updated: -1. https://github.com/apache/iceberg/blob/master/.github/ISSUE_TEMPLATE/iceberg_bug_report.yml -2. https://github.com/apache/iceberg/blob/master/python/dev/Dockerfile -3. `oldVersion` in `revapi` in https://github.com/apache/iceberg/blob/master/build.gradle - -### Documentation release +#### Documentation release Documentation needs to be updated as a part of an Iceberg release after a release candidate is passed. -#### Prerequisites +##### Prerequisites Similar to the `iceberg` repository, you also need to set up `https://github.com/apache/iceberg-docs.git` as a remote with name `apache`. @@ -321,7 +293,7 @@ And you are: Adjust the commands below accordingly if it is not the case. -#### Update specs +##### Update specs Copy the latest format specifications to `landing-page/content/common`: @@ -331,7 +303,7 @@ cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/ Raise a PR with the specific changes against `main` branch and merge. -#### Copy versioned documentations +##### Copy versioned documentations Copy the versioned docs into `docs/content` @@ -342,7 +314,7 @@ cp -r ../iceberg/docs ../iceberg-docs/docs/content Raise a PR with the specific changes against `main` branch and merge. -#### Copy versioned Javadoc +##### Copy versioned Javadoc In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder: @@ -356,7 +328,7 @@ cp -r site/docs/javadoc/ ../iceberg-docs/javadoc Raise a PR with the specific changes against `main` branch and merge. -#### Set latest versions +##### Set latest versions The following fields need to be updated: 1. in `landing-page/config.toml`: @@ -369,7 +341,7 @@ The following fields need to be updated: Raise a PR with the specific changes against `main` branch and merge. -### update release notes +##### update release notes In page `landing-page/content/common/release-notes.md`: 1. Mark the current latest release notes to past releases @@ -377,7 +349,7 @@ In page `landing-page/content/common/release-notes.md`: Raise a PR with the specific changes against `main` branch and merge. -#### Create version branch +##### Create version branch Create a branch with the specific version number: @@ -386,7 +358,7 @@ git checkout -b git push --set-upstream apache ``` -#### Update the `latest` branch +##### Update the `latest` branch Since `main` is currently the same as the version branch, one needs to rebase `latest` branch against `main`: @@ -396,6 +368,36 @@ git rebase main git push apache latest ``` +#### Send announcement email + +After every step is completed, send an announcement email: + +```text +[ANNOUNCE] Apache Iceberg release +``` +```text +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, +along with atomic commits, concurrent writes, and SQL-compatible table +evolution. + +This release can be downloaded from: https://www.apache.org/dyn/closer.cgi/iceberg// + +Java artifacts are available from Maven Central. + +Thanks to everyone for contributing! +``` + +#### Iceberg codebase updates + +After the release artifacts are available in Maven, +there are a few places in the codebase that reference the latest Iceberg release version number and need to be updated: +1. Update `options` list for `Apache Iceberg version` in https://github.com/apache/iceberg/blob/master/.github/ISSUE_TEMPLATE/iceberg_bug_report.yml +2. Update `ICEBERG_VERSION` in https://github.com/apache/iceberg/blob/master/python/dev/Dockerfile +3. Update `oldVersion` in `revapi` in https://github.com/apache/iceberg/blob/master/build.gradle + # How to Verify a Release Each Apache Iceberg release is validated by the community by holding a vote. A community release manager From 0d4e7fa8bc252767a2ebf1de03f2c7d0bb9daf81 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Thu, 23 Mar 2023 14:57:47 -0700 Subject: [PATCH 8/9] update header sizes --- landing-page/content/common/how-to-release.md | 38 +++++++++++-------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 7779d32cd..2d16d20db 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -217,10 +217,13 @@ The vote result is: Therefore, the release candidate is passed/rejected. ``` +While waiting for the vote, you can start to draft the release notes. See [Documentation release section](#documentation-release) for more details. -### Finishing the release +## Release artifacts -#### Apache release +After a release candidate is passed, the next step is to release the candidate artifacts. + +### Apache release After the release vote has passed, you need to release the last candidate's artifacts. @@ -237,7 +240,7 @@ svn add apache-iceberg- svn ci -m 'Iceberg: Add release ' ``` -#### GitHub release +### GitHub release Next, add a release tag to the git repository based on the passing candidate tag: @@ -263,19 +266,20 @@ git checkout -b 1.2.x apache-iceberg-1.2.0 git push --set-upstream apache 1.2.x ``` -#### Maven release +### Maven release 1. Go to [Nexus](https://repository.apache.org/) and log in 2. In the menu on the left, choose "Staging Repositories" 3. Select the Iceberg repository that was previously closed and passed vote 4. At the top, select "Release" and follow the instructions -5. Wait until Maven central has mirrored the Apache binaries and the new version shows up in [Maven Central](https://mvnrepository.com/artifact/org.apache.iceberg) (this typically takes 1-2 days) +5. Wait until Maven central has mirrored the Apache binaries and the new version shows up in [Maven Central](https://mvnrepository.com/artifact/org.apache.iceberg). This typically takes 1-2 days, and you can work on documentation updates during this time. -#### Documentation release +## Documentation release Documentation needs to be updated as a part of an Iceberg release after a release candidate is passed. +This can be done while you are waiting for Maven Central to be updated. -##### Prerequisites +### Prerequisites Similar to the `iceberg` repository, you also need to set up `https://github.com/apache/iceberg-docs.git` as a remote with name `apache`. @@ -293,7 +297,7 @@ And you are: Adjust the commands below accordingly if it is not the case. -##### Update specs +### Update specs Copy the latest format specifications to `landing-page/content/common`: @@ -303,7 +307,7 @@ cp -r ../iceberg/format/* ../iceberg-docs/landing-page/content/common/ Raise a PR with the specific changes against `main` branch and merge. -##### Copy versioned documentations +### Copy versioned documentations Copy the versioned docs into `docs/content` @@ -314,7 +318,7 @@ cp -r ../iceberg/docs ../iceberg-docs/docs/content Raise a PR with the specific changes against `main` branch and merge. -##### Copy versioned Javadoc +### Copy versioned Javadoc In the `iceberg` repository, generate the javadoc for your release and copy it to the `javadoc` folder: @@ -328,7 +332,7 @@ cp -r site/docs/javadoc/ ../iceberg-docs/javadoc Raise a PR with the specific changes against `main` branch and merge. -##### Set latest versions +### Set latest versions The following fields need to be updated: 1. in `landing-page/config.toml`: @@ -341,7 +345,7 @@ The following fields need to be updated: Raise a PR with the specific changes against `main` branch and merge. -##### update release notes +### update release notes In page `landing-page/content/common/release-notes.md`: 1. Mark the current latest release notes to past releases @@ -349,7 +353,7 @@ In page `landing-page/content/common/release-notes.md`: Raise a PR with the specific changes against `main` branch and merge. -##### Create version branch +### Create version branch Create a branch with the specific version number: @@ -358,7 +362,7 @@ git checkout -b git push --set-upstream apache ``` -##### Update the `latest` branch +### Update the `latest` branch Since `main` is currently the same as the version branch, one needs to rebase `latest` branch against `main`: @@ -368,7 +372,9 @@ git rebase main git push apache latest ``` -#### Send announcement email +## Finalize release + +### Send announcement email After every step is completed, send an announcement email: @@ -390,7 +396,7 @@ Java artifacts are available from Maven Central. Thanks to everyone for contributing! ``` -#### Iceberg codebase updates +### Update Iceberg codebase After the release artifacts are available in Maven, there are a few places in the codebase that reference the latest Iceberg release version number and need to be updated: From 2f211fd6024b3f3710bc5ce9ac2d7eb37780f359 Mon Sep 17 00:00:00 2001 From: Fokko Driesprong Date: Thu, 1 Jun 2023 14:15:30 +0200 Subject: [PATCH 9/9] Update landing-page/content/common/how-to-release.md Co-authored-by: Eduard Tudenhoefner --- landing-page/content/common/how-to-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/landing-page/content/common/how-to-release.md b/landing-page/content/common/how-to-release.md index 2d16d20db..e1c3581f3 100644 --- a/landing-page/content/common/how-to-release.md +++ b/landing-page/content/common/how-to-release.md @@ -345,7 +345,7 @@ The following fields need to be updated: Raise a PR with the specific changes against `main` branch and merge. -### update release notes +### Update release notes In page `landing-page/content/common/release-notes.md`: 1. Mark the current latest release notes to past releases