You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "ajantha-bhat (via GitHub)" <gi...@apache.org> on 2026/09/18 11:48:09 UTC
[PR] Catalog Migrator: Add release runbook [polaris-tools]
ajantha-bhat opened a new pull request, #273:
URL: https://github.com/apache/polaris-tools/pull/273
## Summary
- add an end-to-end release runbook for Iceberg Catalog Migrator
- cover initial and replacement RCs, artifact staging, voting, and publication
- link the runbook from the Catalog Migrator README
## Testing
- `git diff --check`
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4046440273
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,449 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
Review Comment:
This is based on what I have used for 1.0.0 and 1.1.0 release.
Originally I referred https://github.com/apache/polaris/pull/3359 and made many changes on the way and this run book is project specific and easy for release managers instead of a generic one from the main repo.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "jbonofre (via GitHub)" <gi...@apache.org>.
jbonofre commented on PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#issuecomment-5864165348
@ajantha-bhat that's great, I wasn't sure (too early in the morning for me 😄 ). I will do the review, thanks againt!
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4135008714
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,469 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Before the planned release, start a `[DISCUSS]` thread on
+`dev@polaris.apache.org` to agree on scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Signing is required for every release. Configure the signing key in the
+user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+```
+
+If Gradle cannot locate `gpg`, configure its executable explicitly:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Provide Nexus credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
Review Comment:
`Keep secrets out of shell`: suggestion `read -s ORG_GRADLE_PROJECT_apachePassword; export ORG_GRADLE_PROJECT_apachePassword`
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "jbonofre (via GitHub)" <gi...@apache.org>.
jbonofre commented on PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#issuecomment-5863471288
@ajantha-bhat FYI, we have an issue (I don't remember if we already have a PR) on the `apache/polaris` repo to update the website/documentation with tool release guide.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4134934388
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Or provide credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
+history.
+
+## 3. Prepare a clean release checkout
+
+Use a fresh clone or dedicated worktree:
+
+```shell
+git clone git@github.com:apache/polaris-tools.git polaris-tools-release
+cd polaris-tools-release
+git remote get-url origin
+git fetch origin --tags
+export REPO_ROOT="$(git rev-parse --show-toplevel)"
+```
+
+Confirm the remote identifies `apache/polaris-tools`, then set the coordinates:
+
+```shell
+export VERSION="x.y.z"
+export RC="0"
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+export TOOL="iceberg-catalog-migrator"
+export RELEASE_BRANCH="release/${TOOL}/${VERSION}"
+export RC_TAG="apache-polaris-${TOOL}-${VERSION}-rc${RC}"
+export RELEASE_TAG="apache-polaris-${TOOL}-${VERSION}"
+export SOURCE_BASE="apache-polaris-${TOOL}-${VERSION}"
+export BINARY_BASE="iceberg-catalog-migrator-cli-${VERSION}"
+```
+
+### 3.1. Select the Java version without creating release input
+
+Use a JDK supported by the current build. Java 21 is the current minimum, but
+that may increase in future releases.
+
+```shell
+java -version
+```
+
+With jenv, select the JDK for the current shell:
+
+```shell
+export JENV_VERSION="<INSTALLED_SUPPORTED_JAVA_VERSION>"
+java -version
+```
+
+Do not run `jenv local` inside the subproject: its `.java-version` file fails
+RAT. `git status --short` must be empty before building.
+
+## 4. Prepare the release branch
+
+### 4.1. First release candidate
+
+For RC0, branch from current `main` and commit the release version:
+
+```shell
+cd "${REPO_ROOT}"
+git checkout main
+git pull --ff-only origin main
Review Comment:
good point :+1:
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat merged PR #273:
URL: https://github.com/apache/polaris-tools/pull/273
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4123100009
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
Review Comment:
The release discuss thread is not optional, is it? If it's not there the release manager will be acting unilaterally... which is not nice 🤔 I think we need to discuss in all case, and maybe proceed after a "timeout" by lazy consensus.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
Review Comment:
When is signing _not_ required? 🤔
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Or provide credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
+history.
+
+## 3. Prepare a clean release checkout
+
+Use a fresh clone or dedicated worktree:
+
+```shell
+git clone git@github.com:apache/polaris-tools.git polaris-tools-release
+cd polaris-tools-release
+git remote get-url origin
+git fetch origin --tags
+export REPO_ROOT="$(git rev-parse --show-toplevel)"
+```
+
+Confirm the remote identifies `apache/polaris-tools`, then set the coordinates:
+
+```shell
+export VERSION="x.y.z"
+export RC="0"
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+export TOOL="iceberg-catalog-migrator"
+export RELEASE_BRANCH="release/${TOOL}/${VERSION}"
+export RC_TAG="apache-polaris-${TOOL}-${VERSION}-rc${RC}"
+export RELEASE_TAG="apache-polaris-${TOOL}-${VERSION}"
+export SOURCE_BASE="apache-polaris-${TOOL}-${VERSION}"
+export BINARY_BASE="iceberg-catalog-migrator-cli-${VERSION}"
+```
+
+### 3.1. Select the Java version without creating release input
+
+Use a JDK supported by the current build. Java 21 is the current minimum, but
+that may increase in future releases.
+
+```shell
+java -version
+```
+
+With jenv, select the JDK for the current shell:
+
+```shell
+export JENV_VERSION="<INSTALLED_SUPPORTED_JAVA_VERSION>"
+java -version
+```
+
+Do not run `jenv local` inside the subproject: its `.java-version` file fails
+RAT. `git status --short` must be empty before building.
+
+## 4. Prepare the release branch
+
+### 4.1. First release candidate
+
+For RC0, branch from current `main` and commit the release version:
+
+```shell
+cd "${REPO_ROOT}"
+git checkout main
+git pull --ff-only origin main
Review Comment:
optional: We ran `fetch` before. Here it may be best to do `git reset --hard orgin/main`
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
Review Comment:
I'm not sure instructing users to put ASF secrets in a common location (`~/.gradle/gradle.properties`) is a good idea 🤔 I'd rather stick to env-based approach (below) as default instructions. Astute users can always use properties if they want to, but it will be their call.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Or provide credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
+history.
+
+## 3. Prepare a clean release checkout
+
+Use a fresh clone or dedicated worktree:
+
+```shell
+git clone git@github.com:apache/polaris-tools.git polaris-tools-release
+cd polaris-tools-release
+git remote get-url origin
Review Comment:
Why is `get-url` necessary?
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4143115133
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,469 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Before the planned release, start a `[DISCUSS]` thread on
+`dev@polaris.apache.org` to agree on scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Signing is required for every release. Configure the signing key in the
+user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+```
+
+If Gradle cannot locate `gpg`, configure its executable explicitly:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Provide Nexus credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
Review Comment:
Nice suggestion, thanks! Updated the runbook to read the Nexus password or token silently, export it for Gradle, and unset it after the final Nexus operation.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#discussion_r4133688783
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
Review Comment:
Agreed. Nexus credentials are now documented only through environment variables; `~/.gradle/gradle.properties` contains only the non-secret signing configuration.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
Review Comment:
Signing is always required. The conditional wording referred only to explicitly configuring the `gpg` executable. Updated to make that distinction clear.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Or provide credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
+history.
+
+## 3. Prepare a clean release checkout
+
+Use a fresh clone or dedicated worktree:
+
+```shell
+git clone git@github.com:apache/polaris-tools.git polaris-tools-release
+cd polaris-tools-release
+git remote get-url origin
Review Comment:
This is a safety check that `origin` points to `apache/polaris-tools` before fetching or pushing release refs. Updated the surrounding text to make its purpose explicit.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
Review Comment:
Agreed. Updated the runbook to require a `[DISCUSS]` thread before the planned release, without prescribing a fixed timeline.
##########
iceberg-catalog-migrator/RELEASING.md:
##########
@@ -0,0 +1,455 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Releasing Apache Polaris Iceberg Catalog Migrator
+
+**Audience:** release managers
+
+This runbook covers manual releases from `apache/polaris-tools`. Commands use
+`origin` for the Apache Git remote; substitute another remote name if needed.
+
+## 1. Prerequisites
+
+* commit and tag access to <https://github.com/apache/polaris-tools>;
+* ASF access to `dist.apache.org` and `repository.apache.org`;
+* a GPG key published in Polaris
+ [KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server;
+* Git, Subversion, GPG, a JDK supported by the current build, and GNU tar
+ (`gtar` on macOS); and
+* a clean checkout of the Apache repository.
+
+Never store ASF passwords, Nexus tokens, signing-key passphrases, or other
+credentials in this repository, release artifacts, logs, or release emails.
+
+Optionally start a `[DISCUSS]` thread on `dev@polaris.apache.org` to agree on
+scope and release blockers.
+
+## 2. Configure release signing
+
+### 2.1. Create or reuse a GPG key
+
+Skip generation if a suitable signing key already exists:
+
+```shell
+gpg --list-secret-keys --keyid-format LONG
+gpg --fingerprint "<KEY_ID>"
+```
+
+Otherwise, follow the
+[ASF signing guide](https://infra.apache.org/release-signing.html):
+
+```shell
+gpg --full-generate-key
+```
+
+Use the full fingerprint as `KEY_ID` and protect the private key and revocation
+certificate.
+
+### 2.2. Publish the public key
+
+Skip this section if the key is already in
+[KEYS](https://downloads.apache.org/polaris/KEYS) and on a public key server.
+Never remove older keys.
+
+To add a new key:
+
+```shell
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+svn checkout https://dist.apache.org/repos/dist/release/polaris polaris-dist-release
+cd polaris-dist-release
+printf '\n' >> KEYS
+gpg --list-sigs "${KEY_ID}" >> KEYS
+gpg --armor --export "${KEY_ID}" >> KEYS
+svn diff KEYS
+svn commit KEYS -m "Update key for <RELEASE_MANAGER>"
+```
+
+```shell
+gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "${KEY_ID}"
+```
+
+Wait until it is visible at <https://downloads.apache.org/polaris/KEYS>.
+
+### 2.3. Configure Gradle signing and Nexus credentials
+
+Configure user-level `~/.gradle/gradle.properties`:
+
+```properties
+signing.gnupg.keyName=<FULL_GPG_FINGERPRINT>
+apacheUsername=<ASF_ID>
+apachePassword=<NEXUS_TOKEN_OR_PASSWORD>
+```
+
+If required:
+
+```properties
+signing.gnupg.executable=gpg
+```
+
+Or provide credentials through the environment:
+
+```shell
+export ORG_GRADLE_PROJECT_apacheUsername="<ASF_ID>"
+export ORG_GRADLE_PROJECT_apachePassword="<NEXUS_TOKEN_OR_PASSWORD>"
+```
+
+Use the ASF ID, not the token name, as the username. Keep secrets out of shell
+history.
+
+## 3. Prepare a clean release checkout
+
+Use a fresh clone or dedicated worktree:
+
+```shell
+git clone git@github.com:apache/polaris-tools.git polaris-tools-release
+cd polaris-tools-release
+git remote get-url origin
+git fetch origin --tags
+export REPO_ROOT="$(git rev-parse --show-toplevel)"
+```
+
+Confirm the remote identifies `apache/polaris-tools`, then set the coordinates:
+
+```shell
+export VERSION="x.y.z"
+export RC="0"
+export KEY_ID="<FULL_GPG_FINGERPRINT>"
+export TOOL="iceberg-catalog-migrator"
+export RELEASE_BRANCH="release/${TOOL}/${VERSION}"
+export RC_TAG="apache-polaris-${TOOL}-${VERSION}-rc${RC}"
+export RELEASE_TAG="apache-polaris-${TOOL}-${VERSION}"
+export SOURCE_BASE="apache-polaris-${TOOL}-${VERSION}"
+export BINARY_BASE="iceberg-catalog-migrator-cli-${VERSION}"
+```
+
+### 3.1. Select the Java version without creating release input
+
+Use a JDK supported by the current build. Java 21 is the current minimum, but
+that may increase in future releases.
+
+```shell
+java -version
+```
+
+With jenv, select the JDK for the current shell:
+
+```shell
+export JENV_VERSION="<INSTALLED_SUPPORTED_JAVA_VERSION>"
+java -version
+```
+
+Do not run `jenv local` inside the subproject: its `.java-version` file fails
+RAT. `git status --short` must be empty before building.
+
+## 4. Prepare the release branch
+
+### 4.1. First release candidate
+
+For RC0, branch from current `main` and commit the release version:
+
+```shell
+cd "${REPO_ROOT}"
+git checkout main
+git pull --ff-only origin main
Review Comment:
Since the runbook requires a clean checkout, I kept `git pull --ff-only`. It fails safely if the local branch has diverged, whereas `git reset --hard origin/main` could discard unexpected local work.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Catalog Migrator: Add release runbook [polaris-tools]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on PR #273:
URL: https://github.com/apache/polaris-tools/pull/273#issuecomment-5863800038
@jbonofre : I have already linked your PR here https://github.com/apache/polaris-tools/pull/273#discussion_r4046440273.
But that PR is very generic and for each reelase, I have to replace many things in that and some binaries are project specific. So, I think this is better. People can use this like a ready script. It is inspired by your PR itself.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org