[GitHub] [iceberg-docs] nastra commented on a diff in pull request #210: Update how to release instructions with more details

["nastra (via GitHub)" <gi...@apache.org>]

nastra commented on code in PR #210:
URL: https://github.com/apache/iceberg-docs/pull/210#discussion_r1147191119


##########
landing-page/content/common/how-to-release.md:
##########
@@ -235,92 +240,130 @@ svn add apache-iceberg-<VERSION>
 svn ci -m 'Iceberg: Add release <VERSION>'
 ```
 
+### GitHub release
+
 Next, add a release tag to the git repository based on the passing candidate tag:
 
 ```bash
 git tag -am 'Release Apache Iceberg <VERSION>' apache-iceberg-<VERSION> apache-iceberg-<VERSION>-rcN
+git push apache apache-iceberg-<VERSION>
 ```
 
-Then release the candidate repository in [Nexus](https://repository.apache.org/#stagingRepositories).
+Then create a new GitHub release in https://github.com/apache/iceberg/releases from the release version tag.
 
-To announce the release, wait until Maven central has mirrored the Apache binaries, then update the Iceberg site and send an announcement email:
+Next, clean up each RC tag with:
 
-```text
-[ANNOUNCE] Apache Iceberg release <VERSION>
+```bash
+git push --delete apache apache-iceberg-<VERSION>-rcN
 ```
-```text
-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,
-along with atomic commits, concurrent writes, and SQL-compatible table
-evolution.
+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:
 
-This release can be downloaded from: https://www.apache.org/dyn/closer.cgi/iceberg/<TARBALL NAME WITHOUT .tar.gz>/<TARBALL NAME>
+```bash
+git checkout -b 1.2.x apache-iceberg-1.2.0
+git push --set-upstream apache 1.2.x
+```
 
-Java artifacts are available from Maven Central.
+### Maven release
 
-Thanks to everyone for contributing!
-```
+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, 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.
-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. 
+This can be done while you are waiting for Maven Central to be updated.
+
+### 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`.
+
+The commands described below assume you have a directory structure of:
+
+```text
+/some/path
+├── iceberg
+└── iceberg-docs
+```
 
-#### iceberg repository preparations
+And you are:
+1. in the `iceberg-docs` repository.
+2. have `iceberg` repository on the specific version branch
 
-A PR needs to be published in the `iceberg` repository with the following changes:
+Adjust the commands below accordingly if it is not the case.
 
-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.
+### Update specs
 
-#### Common documentation update
+Copy the latest format specifications to `landing-page/content/common`:
 
-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`)
 
-#### Versioned documentation update
+Raise a PR with the specific changes against `main` branch and merge.
 
-Once the common docs changes have been merged into `main`, the next step is to update the versioned docs.
+### Copy versioned documentations
+
+Copy the versioned docs into `docs/content`
 
-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 <VERSION>
-git push --set-upstream apache <VERSION>
-```
-2. Copy the versioned docs from the `iceberg` repo into the `iceberg-docs` repo
 ```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 `<VERSION>` branch in the `iceberg-docs` repo
 
-#### Javadoc update
+Raise a PR with the specific changes against `main` 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>" > version.txt
 ./gradlew refreshJavadoc
 rm -rf ../iceberg-docs/javadoc
-cp -r site/docs/javadoc/<VERSION NUMBER> ../iceberg-docs/javadoc
+cp -r site/docs/javadoc/<VERSION> ../iceberg-docs/javadoc
 ```
 
-This resulted changes in `iceberg-docs` should be approved in a separate PR.
+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

Review Comment:
   ```suggestion
   ### Update release notes
   ```



-- 
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