From d9b87cb43f58cca9336c1021c5e648017ba47b77 Mon Sep 17 00:00:00 2001 From: Russell Spitzer Date: Thu, 12 Nov 2026 13:49:38 -0600 Subject: [PATCH 1/5] Releasing Parquet-Java: document the GitHub Actions workflows The release is now run with the Prepare RC, Cancel RC, and Publish After Vote workflows in apache/parquet-java. Replace the manual steps (prepare-release.sh, release:perform, closing and releasing in Nexus, source-release.sh, finalize-release) with how to run each workflow, its inputs, and what it does. The dist.apache.org promotion stays a manual PMC step because the workflow credentials can only write to dist/dev; the page shows the svn commands that the Publish summary prints. The verification guide is unchanged. Generated-by: Claude Opus 5.5 --- .../docs/Contribution Guidelines/releasing.md | 247 +++++++++--------- 1 file changed, 128 insertions(+), 119 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/releasing.md b/content/en/docs/Contribution Guidelines/releasing.md index c36375a7..8a7fe121 100644 --- a/content/en/docs/Contribution Guidelines/releasing.md +++ b/content/en/docs/Contribution Guidelines/releasing.md @@ -23,175 +23,176 @@ description: > How to release Parquet-Java --- -### Setup - -N.B. The mechanics of releasing parquet-format is the same (e.g. setting up keys, branching, votes, etc) - -You will need: +### Overview -- PGP code signing keys, published in [KEYS](https://downloads.apache.org/parquet/KEYS). -- Permission to stage artifacts in [Nexus](https://repository.apache.org/). +Parquet-Java releases are run with three GitHub Actions workflows in +[apache/parquet-java](https://github.com/apache/parquet-java/actions). The +workflows tag the release, stage and publish the Maven artifacts in Nexus, +stage the source tarball on dist.apache.org, create the GitHub releases, and +write the e-mails for the release manager to send. -Make sure you have permission to deploy Parquet artifacts to Nexus by pushing a snapshot: - -```sh -mvn deploy -``` +| Workflow | When to run it | Branch to run it from | +| --- | --- | --- | +| **Release - Prepare RC** | To create a release candidate | `master` for a new minor release, `parquet-X.Y.x` for a patch release | +| **Release - Cancel RC** | When a vote fails | Any | +| **Release - Publish After Vote** | When a vote passes | `parquet-X.Y.x` | -If you have problems, read the [publishing Maven artifacts documentation](https://www.apache.org/dev/publishing-maven-artifacts.html). - -### Release process - -Parquet uses the maven-release-plugin to tag a release and push binary artifacts to staging in Nexus. Once maven completes the release, the official source tarball is built from the tag. - -#### 0\. Before you start the release process +To run a workflow, open the [Actions tab](https://github.com/apache/parquet-java/actions), +select the workflow, click **Run workflow**, choose the branch, and fill in the inputs. -1. Verify that the release is finished (no planned Issues/PRs are pending [on the milestone](https://github.com/apache/parquet-java/milestones)) -1. Build and test the project -1. Create a new branch for the release if this is a new minor version. For example, if the new minor version is 1.14.0, create a new branch `parquet-1.14.x` +Every workflow has a **Dry run** input, which is selected by default. A dry +run prints each command without running it. Always do a dry run first, read +its summary, and then run the workflow again with **Dry run** cleared. -#### 1\. Run the prepare script +Each run writes its results, the next steps, and any e-mail text to the run's +**Summary** page. Keep the summary of the Prepare RC run: the Publish and +Cancel workflows need the Nexus staging repository ID from it. -```sh -./dev/prepare-release.sh -``` +N.B. These workflows release parquet-java only. The mechanics of releasing +parquet-format (keys, branches, votes) are the same, but its steps are manual. -This runs maven’s release prepare with a consistent tag name. After this step, the release tag will exist in the git repository. +### Setup -If this step fails, you can roll back the changes by running these commands. +You will need: -```sh -find ./ -type f -name '*.releaseBackup' -exec rm {} \; -find ./ -type f -name 'pom.xml' -exec git checkout {} \; -``` +- Write access to apache/parquet-java, to run the workflows. +- PMC membership, or a PMC member to help you, for the final step on + dist.apache.org. The workflow credentials can write only to + `dist/dev/parquet`; moving a release into `dist/release/parquet` needs a + PMC member's SVN credentials. -#### 2\. Run release:perform to stage binaries +The workflows use credentials stored as repository secrets: +`PARQUET_GPG_PRIVATE_KEY` signs the release, `NEXUS_STAGE_DEPLOYER_USER` and +`NEXUS_STAGE_DEPLOYER_PW` deploy to [Nexus](https://repository.apache.org/), +and `PARQUET_SVN_DEV_USERNAME` and `PARQUET_SVN_DEV_PASSWORD` write to +`dist/dev/parquet`. The public key for the signing key must be in +[KEYS](https://downloads.apache.org/parquet/KEYS). -Upload binary artifacts for the release tag to [Nexus](https://repository.apache.org/): +### Release process -```sh -mvn release:perform -DskipTests -Darguments=-DskipTests -``` +#### 0\. Before you start the release process -#### 3\. In Nexus, close the staging repository +1. Verify that the release is finished (no planned Issues/PRs are pending [on the milestone](https://github.com/apache/parquet-java/milestones)). +1. Make sure CI passes on the commit you will release. The workflow stops if it does not. -Closing a staging repository makes the binaries available in [staging](https://repository.apache.org/content/groups/staging/org/apache/parquet/), but does not publish them. +#### 1\. Run "Release - Prepare RC" -1. Go to [Nexus](https://repository.apache.org/). -2. In the menu on the left, choose “Staging Repositories”. -3. Select the Parquet repository. -4. At the top, click “Close” and follow the instructions. For the comment use “Apache Parquet \[Format\] ”. +Inputs: -#### 4\. Run the source tarball script +- **version**: the release version, for example `1.18.0`. +- **rc_number**: leave empty to use the next free RC number. +- **dry_run**: select it for the first run. -```sh -dev/source-release.sh -``` +For a new minor release, run the workflow from `master`. The workflow creates +the `parquet-X.Y.x` release branch from `master`. For a patch release, run it +from the existing `parquet-X.Y.x` branch. -This script builds the source tarball from the release tag’s SHA1, signs it, and uploads the necessary files with SVN. +The workflow: -The source release is pushed to [https://dist.apache.org/repos/dist/dev/parquet/](https://dist.apache.org/repos/dist/dev/parquet/) +1. Creates the `parquet-X.Y.x` branch, if it does not exist, and checks it out. +1. Finds the next RC number. +1. Verifies that CI passes on the release commit. +1. Sets the POM version to the release version and commits it. +1. Creates the RC tag, for example `apache-parquet-1.18.0-rc0`. +1. Deploys the artifacts to a Nexus staging repository, then closes and verifies it. +1. Builds and signs the source tarball, and writes its SHA-512 checksum. +1. Stages the tarball, signature, and checksum in + [dist/dev/parquet](https://dist.apache.org/repos/dist/dev/parquet/). +1. Pushes the RC tag and creates a GitHub pre-release with generated release notes. +1. Writes the VOTE e-mail in the run summary. -The last message from the script is the release commit’s SHA1 hash and URL for the VOTE e-mail. +Write down the **Nexus staging repository ID** from the summary, for example +`orgapacheparquet-1234`. -### 5\. Prepare the pre-release +#### 2\. Review the pre-release notes -Creating the [pre-release](https://github.com/apache/parquet-java/releases/new) will give the users the changelog to see if they need to validate certain functionality. First select the newly created `rc` (ex: `apache-parquet-1.15.0-rc0`) tag, and then the previous release (ex. `apache-parquet-1.14.1`). Hit the `Generate release notes` button to auto generate the notes. You can curate the notes a bit by removing unrelated changes (whitespace, test-only changes) and sorting them to make them easier to digest. Make sure to check the `Set as pre-release` checkbox as this is a release candidate. +Open the [pre-release](https://github.com/apache/parquet-java/releases) that +the workflow created. You can curate the generated notes: remove unrelated +changes (whitespace, test-only changes) and sort them to make them easier to +read. -#### 6\. Send a VOTE e-mail to [dev@parquet.apache.org](mailto:dev@parquet.apache.org) +#### 3\. Send the VOTE e-mail to [dev@parquet.apache.org](mailto:dev@parquet.apache.org) -Here is a template you can use. Make sure everything applies to your release. +Copy the VOTE e-mail from the run summary. Add a summary of the important +changes in the release, and make sure everything in the e-mail applies to +your release. - Subject: [VOTE] Release Apache Parquet RC +### If the vote fails +Run **Release - Cancel RC** with these inputs: - Hi everyone, +- **version** and **rc_number**: the release candidate that failed. +- **staging_repo_id**: the Nexus staging repository ID from the Prepare RC summary. - I propose the following RC to be released as official Apache Parquet release. +The workflow drops the Nexus staging repository, removes the RC from +`dist/dev/parquet`, and writes the vote result e-mail in the run summary. Fill +in the reason the vote failed and send the e-mail to the dev list. - The commit id is - * This corresponds to the tag: apache-parquet--rc - * https://github.com/apache/parquet-java/tree/ +The RC tag and the GitHub pre-release stay in place, so the RC number is not +used again. After the issues are fixed, run Prepare RC again; it uses the next +RC number. - The release tarball, signature, and checksums are here: - * https://dist.apache.org/repos/dist/dev/parquet/ - - You can find the KEYS file here: - * https://downloads.apache.org/parquet/KEYS +### Publishing after the vote passes - You can find the changelog here: - https://github.com/apache/parquet-java/releases/tag/apache-parquet--rc +#### 1\. Send the vote result e-mail - Binary artifacts are staged in Nexus here: - * https://repository.apache.org/content/groups/staging/org/apache/parquet/ +Send a `[RESULT][VOTE] Release Apache Parquet RC` e-mail to the +dev list with the vote counts. - This release includes important changes that I should have summarized here, but I'm lazy. +#### 2\. Run "Release - Publish After Vote" - Please download, verify, and test. +Run the workflow from the `parquet-X.Y.x` release branch. Inputs: - Please vote in the next 72 hours. +- **version**: the release version, for example `1.18.0`. +- **rc_number**: the RC that passed the vote. Leave empty to use the latest RC. +- **staging_repo_id**: the Nexus staging repository ID from the Prepare RC summary. +- **allow_description_mismatch**: leave it cleared. It is only for recovery + when the staging repository description does not match the RC. +- **dry_run**: select it for the first run. - [ ] +1 Release this as Apache Parquet - [ ] +0 - [ ] -1 Do not release this because... +Before it changes anything, the workflow verifies that the staging repository +belongs to `org.apache.parquet`, is closed, contains the release version, and +has the description `Apache Parquet RC`. The workflow then: +1. Creates the final release tag, for example `apache-parquet-1.18.0`, on the RC commit. +1. Releases the Nexus staging repository to Maven Central. +1. Pushes the release tag and creates the GitHub release. +1. Sets the next development version, for example `1.18.1-SNAPSHOT`, on the + release branch and pushes it. +1. Writes the remaining manual steps and the ANNOUNCE e-mail in the run summary. +#### 3\. Move the release on dist.apache.org (PMC member) -### Publishing after the vote passes +The run summary has a block of `svn` commands for the release. A PMC member +copies the block and runs it with their own SVN credentials. The commands: -After a release candidate passes a vote, the candidate needs to be published as the final release. +- Move the RC from `dist/dev/parquet` to `dist/release/parquet`. +- Remove older patch releases of the same minor version that the new release + replaces. Releases of other minor versions are not changed. -#### 1\. Tag final release and set development version +For example, for 1.14.3: ```sh -./dev/finalize-release +svn mv https://dist.apache.org/repos/dist/dev/parquet/apache-parquet-1.14.3-rc0 \ + https://dist.apache.org/repos/dist/release/parquet/apache-parquet-1.14.3 \ + -m "Release Apache Parquet 1.14.3" +svn rm https://dist.apache.org/repos/dist/release/parquet/apache-parquet-1.14.2 \ + -m "Remove old release apache-parquet-1.14.2 (superseded by 1.14.3)" ``` -This will add the final release tag to the RC tag and sets the new development version in the pom files. If everything is fine push the changes and the new tag to GitHub: `git push --follow-tags` - -#### 2\. Release the binary repository in Nexus - -Releasing a binary repository publishes the binaries to [public](https://repository.apache.org/content/groups/public/org/apache/parquet/). - -1. Go to [Nexus](https://repository.apache.org/). -2. In the menu on the left, choose “Staging Repositories”. -3. Select the Parquet repository. -4. At the top, click Release and follow the instructions. For the comment use “Apache Parquet \[Format\] ”. - -#### 3\. Copy the release artifacts in SVN into releases - -First, check out the candidates and releases locations in SVN: - -```sh -svn mv https://dist.apache.org/repos/dist/dev/parquet/apache-parquet--rcN/ https://dist.apache.org/repos/dist/release/parquet/apache-parquet- -m "Parquet: Add release " -``` +Removed releases stay available on [archive.apache.org](https://archive.apache.org/dist/parquet/). #### 4\. Update parquet.apache.org -Update the downloads page on parquet.apache.org. Instructions for updating the site are on the [contribution page](https://parquet.apache.org/docs/contribution-guidelines/contributing/). +Update the downloads page on parquet.apache.org and add a release blog post. +The run summary has a template for the blog post. Instructions for updating +the site are on the [contribution page](https://parquet.apache.org/docs/contribution-guidelines/contributing/). -### 5\. Add the release to GitHub +#### 5\. Send the ANNOUNCE e-mail to [announce@apache.org](mailto:announce@apache.org) and the dev list -Add a [new release to GitHub](https://github.com/apache/parquet-java/releases/new). First select the newly tag (ex: `apache-parquet-1.15.0`), and then the previous release (ex. `apache-parquet-1.14.1`). You can copy the release notes from the RC that passed the vote. - -#### 6\. Send an ANNOUNCE e-mail to [announce@apache.org](mailto:announce@apache.org) and the dev list - - [ANNOUNCE] Apache Parquet release - - - I'm pleased to announce the release of Parquet ! - - Parquet is a general-purpose columnar file format for nested data. It uses - space-efficient encodings and a compressed and splittable structure for - processing frameworks like Hadoop. - - Changes are listed at: https://github.com/apache/parquet-java/releases/tag/apache-parquet- - - This release can be downloaded from: https://parquet.apache.org/downloads/ - - Java artifacts are available from Maven Central. - - Thanks to everyone for contributing! +Copy the ANNOUNCE e-mail from the run summary. The e-mail links to the +downloads page, so send it after the release is on +[downloads.apache.org](https://downloads.apache.org/parquet/) and the site is updated. #### 6\. Update parquet-format with feature enablement guidance @@ -200,6 +201,14 @@ parquet-java (details are in the parquet-format repo). As releases are made the specification should be updated to indicate the recommended dates for when a new feature may be enabled. +### Running the release scripts locally + +Each workflow runs a script in +[`release/bin`](https://github.com/apache/parquet-java/tree/master/release/bin) +of parquet-java. You can run the scripts on your own machine, for example to +debug a failed run. See the +[release README](https://github.com/apache/parquet-java/blob/master/release/README.md) +for details. ### Release Cadence From a1fe805bb5ea581845d5cb69c3f464f7f6bbe996 Mon Sep 17 00:00:00 2001 From: Russell Spitzer Date: Thu, 12 Nov 2026 14:00:27 -0600 Subject: [PATCH 2/5] Releasing Parquet-Java: run every release workflow from master Prepare RC and Publish After Vote check out the parquet-X.Y.x release branch themselves, so the page no longer tells release managers to pick a release branch when they run them. Generated-by: Claude Opus 5.5 --- .../docs/Contribution Guidelines/releasing.md | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/releasing.md b/content/en/docs/Contribution Guidelines/releasing.md index 8a7fe121..3ad8b35f 100644 --- a/content/en/docs/Contribution Guidelines/releasing.md +++ b/content/en/docs/Contribution Guidelines/releasing.md @@ -31,14 +31,16 @@ workflows tag the release, stage and publish the Maven artifacts in Nexus, stage the source tarball on dist.apache.org, create the GitHub releases, and write the e-mails for the release manager to send. -| Workflow | When to run it | Branch to run it from | -| --- | --- | --- | -| **Release - Prepare RC** | To create a release candidate | `master` for a new minor release, `parquet-X.Y.x` for a patch release | -| **Release - Cancel RC** | When a vote fails | Any | -| **Release - Publish After Vote** | When a vote passes | `parquet-X.Y.x` | +| Workflow | When to run it | +| --- | --- | +| **Release - Prepare RC** | To create a release candidate | +| **Release - Cancel RC** | When a vote fails | +| **Release - Publish After Vote** | When a vote passes | To run a workflow, open the [Actions tab](https://github.com/apache/parquet-java/actions), -select the workflow, click **Run workflow**, choose the branch, and fill in the inputs. +select the workflow, click **Run workflow**, and fill in the inputs. Always run +the workflows from `master`. The Prepare RC and Publish workflows find the +`parquet-X.Y.x` release branch from the version and check it out themselves. Every workflow has a **Dry run** input, which is selected by default. A dry run prints each command without running it. Always do a dry run first, read @@ -73,6 +75,7 @@ and `PARQUET_SVN_DEV_USERNAME` and `PARQUET_SVN_DEV_PASSWORD` write to #### 0\. Before you start the release process 1. Verify that the release is finished (no planned Issues/PRs are pending [on the milestone](https://github.com/apache/parquet-java/milestones)). +1. For a patch release, backport the fixes to the `parquet-X.Y.x` branch. 1. Make sure CI passes on the commit you will release. The workflow stops if it does not. #### 1\. Run "Release - Prepare RC" @@ -83,9 +86,9 @@ Inputs: - **rc_number**: leave empty to use the next free RC number. - **dry_run**: select it for the first run. -For a new minor release, run the workflow from `master`. The workflow creates -the `parquet-X.Y.x` release branch from `master`. For a patch release, run it -from the existing `parquet-X.Y.x` branch. +For a new minor release, the workflow creates the `parquet-X.Y.x` release +branch from `master`. For a patch release, it uses the existing +`parquet-X.Y.x` branch. The workflow: @@ -141,7 +144,7 @@ dev list with the vote counts. #### 2\. Run "Release - Publish After Vote" -Run the workflow from the `parquet-X.Y.x` release branch. Inputs: +Inputs: - **version**: the release version, for example `1.18.0`. - **rc_number**: the RC that passed the vote. Leave empty to use the latest RC. @@ -152,7 +155,9 @@ Run the workflow from the `parquet-X.Y.x` release branch. Inputs: Before it changes anything, the workflow verifies that the staging repository belongs to `org.apache.parquet`, is closed, contains the release version, and -has the description `Apache Parquet RC`. The workflow then: +has the description `Apache Parquet RC`. It also checks out the +`parquet-X.Y.x` branch and verifies that its head is the RC commit. The +workflow then: 1. Creates the final release tag, for example `apache-parquet-1.18.0`, on the RC commit. 1. Releases the Nexus staging repository to Maven Central. From 96393831ff07ff5ffe4124be92b36c04f960545b Mon Sep 17 00:00:00 2001 From: Russell Spitzer Date: Thu, 12 Nov 2026 14:03:04 -0600 Subject: [PATCH 3/5] Releasing Parquet-Java: list every workflow input Each workflow now has a table of its inputs with the default and what the input does. Numbered lists use explicit numbers so that the source reads the same as the rendered page. Generated-by: Claude Opus 5.5 --- .../docs/Contribution Guidelines/releasing.md | 68 +++++++++++-------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/releasing.md b/content/en/docs/Contribution Guidelines/releasing.md index 3ad8b35f..d09b1a56 100644 --- a/content/en/docs/Contribution Guidelines/releasing.md +++ b/content/en/docs/Contribution Guidelines/releasing.md @@ -75,16 +75,16 @@ and `PARQUET_SVN_DEV_USERNAME` and `PARQUET_SVN_DEV_PASSWORD` write to #### 0\. Before you start the release process 1. Verify that the release is finished (no planned Issues/PRs are pending [on the milestone](https://github.com/apache/parquet-java/milestones)). -1. For a patch release, backport the fixes to the `parquet-X.Y.x` branch. -1. Make sure CI passes on the commit you will release. The workflow stops if it does not. +2. For a patch release, backport the fixes to the `parquet-X.Y.x` branch. +3. Make sure CI passes on the commit you will release. The workflow stops if it does not. #### 1\. Run "Release - Prepare RC" -Inputs: - -- **version**: the release version, for example `1.18.0`. -- **rc_number**: leave empty to use the next free RC number. -- **dry_run**: select it for the first run. +| Input | Required | Default | Description | +| --- | --- | --- | --- | +| `version` | Yes | | The release version, for example `1.18.0`. | +| `rc_number` | No | Next free RC number | The RC number. Set it only to override the next free number; the workflow stops if the RC tag already exists. | +| `dry_run` | No | Selected | Print each command without running it. | For a new minor release, the workflow creates the `parquet-X.Y.x` release branch from `master`. For a patch release, it uses the existing @@ -93,16 +93,16 @@ branch from `master`. For a patch release, it uses the existing The workflow: 1. Creates the `parquet-X.Y.x` branch, if it does not exist, and checks it out. -1. Finds the next RC number. -1. Verifies that CI passes on the release commit. -1. Sets the POM version to the release version and commits it. -1. Creates the RC tag, for example `apache-parquet-1.18.0-rc0`. -1. Deploys the artifacts to a Nexus staging repository, then closes and verifies it. -1. Builds and signs the source tarball, and writes its SHA-512 checksum. -1. Stages the tarball, signature, and checksum in +2. Finds the next RC number. +3. Verifies that CI passes on the release commit. +4. Sets the POM version to the release version and commits it. +5. Creates the RC tag, for example `apache-parquet-1.18.0-rc0`. +6. Deploys the artifacts to a Nexus staging repository, then closes and verifies it. +7. Builds and signs the source tarball, and writes its SHA-512 checksum. +8. Stages the tarball, signature, and checksum in [dist/dev/parquet](https://dist.apache.org/repos/dist/dev/parquet/). -1. Pushes the RC tag and creates a GitHub pre-release with generated release notes. -1. Writes the VOTE e-mail in the run summary. +9. Pushes the RC tag and creates a GitHub pre-release with generated release notes. +10. Writes the VOTE e-mail in the run summary. Write down the **Nexus staging repository ID** from the summary, for example `orgapacheparquet-1234`. @@ -124,8 +124,17 @@ your release. Run **Release - Cancel RC** with these inputs: -- **version** and **rc_number**: the release candidate that failed. -- **staging_repo_id**: the Nexus staging repository ID from the Prepare RC summary. +| Input | Required | Default | Description | +| --- | --- | --- | --- | +| `version` | Yes | | The release version, for example `1.18.0`. | +| `rc_number` | Yes | | The RC number that failed the vote, for example `0`. | +| `staging_repo_id` | Yes | | The Nexus staging repository ID from the Prepare RC summary, for example `orgapacheparquet-1234`. | +| `allow_description_mismatch` | No | Cleared | Skip the check that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when the description was changed by hand. | +| `dry_run` | No | Selected | Print each command without running it. | + +Before it drops the staging repository, the workflow verifies that the +repository belongs to `org.apache.parquet`, is closed, contains the release +version, and has the expected description. The workflow drops the Nexus staging repository, removes the RC from `dist/dev/parquet`, and writes the vote result e-mail in the run summary. Fill @@ -144,14 +153,13 @@ dev list with the vote counts. #### 2\. Run "Release - Publish After Vote" -Inputs: - -- **version**: the release version, for example `1.18.0`. -- **rc_number**: the RC that passed the vote. Leave empty to use the latest RC. -- **staging_repo_id**: the Nexus staging repository ID from the Prepare RC summary. -- **allow_description_mismatch**: leave it cleared. It is only for recovery - when the staging repository description does not match the RC. -- **dry_run**: select it for the first run. +| Input | Required | Default | Description | +| --- | --- | --- | --- | +| `version` | Yes | | The release version, for example `1.18.0`. | +| `rc_number` | No | Latest RC | The RC number that passed the vote. It must be the latest RC for the version. | +| `staging_repo_id` | Yes | | The Nexus staging repository ID from the Prepare RC summary, for example `orgapacheparquet-1234`. | +| `allow_description_mismatch` | No | Cleared | Skip the check that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when the description was changed by hand. | +| `dry_run` | No | Selected | Print each command without running it. | Before it changes anything, the workflow verifies that the staging repository belongs to `org.apache.parquet`, is closed, contains the release version, and @@ -160,11 +168,11 @@ has the description `Apache Parquet RC`. It also checks out the workflow then: 1. Creates the final release tag, for example `apache-parquet-1.18.0`, on the RC commit. -1. Releases the Nexus staging repository to Maven Central. -1. Pushes the release tag and creates the GitHub release. -1. Sets the next development version, for example `1.18.1-SNAPSHOT`, on the +2. Releases the Nexus staging repository to Maven Central. +3. Pushes the release tag and creates the GitHub release. +4. Sets the next development version, for example `1.18.1-SNAPSHOT`, on the release branch and pushes it. -1. Writes the remaining manual steps and the ANNOUNCE e-mail in the run summary. +5. Writes the remaining manual steps and the ANNOUNCE e-mail in the run summary. #### 3\. Move the release on dist.apache.org (PMC member) From 674f54b4a8818c9ef8e18aa764acdc18f3185860 Mon Sep 17 00:00:00 2001 From: Russell Spitzer Date: Thu, 12 Nov 2026 14:04:27 -0600 Subject: [PATCH 4/5] Releasing Parquet-Java: show the automated release signing key The key is already in KEYS, so link to KEYS and show the key's fingerprint instead of saying that it must be added. Generated-by: Claude Opus 5.5 --- content/en/docs/Contribution Guidelines/releasing.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/releasing.md b/content/en/docs/Contribution Guidelines/releasing.md index d09b1a56..55f0724e 100644 --- a/content/en/docs/Contribution Guidelines/releasing.md +++ b/content/en/docs/Contribution Guidelines/releasing.md @@ -67,8 +67,16 @@ The workflows use credentials stored as repository secrets: `PARQUET_GPG_PRIVATE_KEY` signs the release, `NEXUS_STAGE_DEPLOYER_USER` and `NEXUS_STAGE_DEPLOYER_PW` deploy to [Nexus](https://repository.apache.org/), and `PARQUET_SVN_DEV_USERNAME` and `PARQUET_SVN_DEV_PASSWORD` write to -`dist/dev/parquet`. The public key for the signing key must be in -[KEYS](https://downloads.apache.org/parquet/KEYS). +`dist/dev/parquet`. + +The workflows sign releases with the project's automated release signing key, +which is published in [KEYS](https://downloads.apache.org/parquet/KEYS): + +``` +pub rsa4096 2026-08-31 [SC] + DD1E 0FA3 56E5 268B E450 B2AA A528 E51B CE01 BCFE +uid Apache Parquet Automated Release Signing +``` ### Release process From b43803d564f5b44b5a66addbd2147d367fb02225 Mon Sep 17 00:00:00 2001 From: Russell Spitzer Date: Fri, 20 Nov 2026 13:33:32 -0600 Subject: [PATCH 5/5] Releasing Parquet-Java: simplify the wording of the page Rewrite the page in plain English: short sentences in active voice, no semicolons or phrasal verbs, and lists for steps and conditions. Use one word for each idea, for example "verify" and "checksum". The repository secrets are now in a table. The release cadence and release verification sections also get typo and grammar fixes. Generated-by: Claude Opus 5.5 --- .../docs/Contribution Guidelines/releasing.md | 226 ++++++++++-------- 1 file changed, 128 insertions(+), 98 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/releasing.md b/content/en/docs/Contribution Guidelines/releasing.md index 55f0724e..3fe1ddc7 100644 --- a/content/en/docs/Contribution Guidelines/releasing.md +++ b/content/en/docs/Contribution Guidelines/releasing.md @@ -25,11 +25,12 @@ description: > ### Overview -Parquet-Java releases are run with three GitHub Actions workflows in -[apache/parquet-java](https://github.com/apache/parquet-java/actions). The -workflows tag the release, stage and publish the Maven artifacts in Nexus, -stage the source tarball on dist.apache.org, create the GitHub releases, and -write the e-mails for the release manager to send. +Three GitHub Actions workflows in +[apache/parquet-java](https://github.com/apache/parquet-java/actions) run the +Parquet-Java releases. The workflows tag the release, stage and publish the +Maven artifacts in Nexus, and stage the source tarball on dist.apache.org. +They also create the GitHub releases and write the e-mails that the release +manager sends. | Workflow | When to run it | | --- | --- | @@ -37,40 +38,52 @@ write the e-mails for the release manager to send. | **Release - Cancel RC** | When a vote fails | | **Release - Publish After Vote** | When a vote passes | -To run a workflow, open the [Actions tab](https://github.com/apache/parquet-java/actions), -select the workflow, click **Run workflow**, and fill in the inputs. Always run -the workflows from `master`. The Prepare RC and Publish workflows find the -`parquet-X.Y.x` release branch from the version and check it out themselves. +To run a workflow: -Every workflow has a **Dry run** input, which is selected by default. A dry -run prints each command without running it. Always do a dry run first, read -its summary, and then run the workflow again with **Dry run** cleared. +1. Open the [Actions tab](https://github.com/apache/parquet-java/actions). +2. Select the workflow. +3. Click **Run workflow**. +4. Set the inputs. -Each run writes its results, the next steps, and any e-mail text to the run's -**Summary** page. Keep the summary of the Prepare RC run: the Publish and -Cancel workflows need the Nexus staging repository ID from it. +Always run the workflows from `master`. The Prepare RC and Publish workflows +use the version to find the `parquet-X.Y.x` release branch. Then they check +out that branch themselves. -N.B. These workflows release parquet-java only. The mechanics of releasing -parquet-format (keys, branches, votes) are the same, but its steps are manual. +Each workflow has a **Dry run** input, and it is selected by default. A dry +run prints each command and does not run it. Always use this sequence: + +1. Do a dry run. +2. Read the summary of the dry run. +3. Run the workflow again with **Dry run** cleared. + +Each run writes its results, the next steps, and any e-mail text to the +**Summary** page of the run. Keep the summary of the Prepare RC run. The +Publish and Cancel RC workflows need the Nexus staging repository ID from it. + +N.B. These workflows release only parquet-java. The steps to release +parquet-format are manual. The mechanics (keys, branches, votes) are the same. ### Setup You will need: - Write access to apache/parquet-java, to run the workflows. -- PMC membership, or a PMC member to help you, for the final step on +- PMC membership, or a PMC member who helps you, for the final step on dist.apache.org. The workflow credentials can write only to - `dist/dev/parquet`; moving a release into `dist/release/parquet` needs a - PMC member's SVN credentials. + `dist/dev/parquet`. A move into `dist/release/parquet` needs the SVN + credentials of a PMC member. -The workflows use credentials stored as repository secrets: -`PARQUET_GPG_PRIVATE_KEY` signs the release, `NEXUS_STAGE_DEPLOYER_USER` and -`NEXUS_STAGE_DEPLOYER_PW` deploy to [Nexus](https://repository.apache.org/), -and `PARQUET_SVN_DEV_USERNAME` and `PARQUET_SVN_DEV_PASSWORD` write to -`dist/dev/parquet`. +The workflows use these repository secrets: + +| Secret | Use | +| --- | --- | +| `PARQUET_GPG_PRIVATE_KEY` | Signs the release. | +| `NEXUS_STAGE_DEPLOYER_USER`, `NEXUS_STAGE_DEPLOYER_PW` | Deploy to [Nexus](https://repository.apache.org/). | +| `PARQUET_SVN_DEV_USERNAME`, `PARQUET_SVN_DEV_PASSWORD` | Write to `dist/dev/parquet`. | -The workflows sign releases with the project's automated release signing key, -which is published in [KEYS](https://downloads.apache.org/parquet/KEYS): +The workflows sign releases with the key "Apache Parquet Automated Release +Signing". The [KEYS](https://downloads.apache.org/parquet/KEYS) file contains +this key: ``` pub rsa4096 2026-08-31 [SC] @@ -82,17 +95,17 @@ uid Apache Parquet Automated Release Signing #### 0\. Before you start the release process -1. Verify that the release is finished (no planned Issues/PRs are pending [on the milestone](https://github.com/apache/parquet-java/milestones)). +1. Verify that the release is complete. No planned issues or PRs are open [on the milestone](https://github.com/apache/parquet-java/milestones). 2. For a patch release, backport the fixes to the `parquet-X.Y.x` branch. -3. Make sure CI passes on the commit you will release. The workflow stops if it does not. +3. Verify that CI passes on the commit that you will release. The workflow stops if CI does not pass. #### 1\. Run "Release - Prepare RC" | Input | Required | Default | Description | | --- | --- | --- | --- | | `version` | Yes | | The release version, for example `1.18.0`. | -| `rc_number` | No | Next free RC number | The RC number. Set it only to override the next free number; the workflow stops if the RC tag already exists. | -| `dry_run` | No | Selected | Print each command without running it. | +| `rc_number` | No | Next free RC number | The RC number. Set it only to override the next free number. The workflow stops if the RC tag already exists. | +| `dry_run` | No | Selected | Print each command and do not run it. | For a new minor release, the workflow creates the `parquet-X.Y.x` release branch from `master`. For a patch release, it uses the existing @@ -100,33 +113,33 @@ branch from `master`. For a patch release, it uses the existing The workflow: -1. Creates the `parquet-X.Y.x` branch, if it does not exist, and checks it out. +1. Creates the `parquet-X.Y.x` branch if it does not exist, then checks out the branch. 2. Finds the next RC number. 3. Verifies that CI passes on the release commit. 4. Sets the POM version to the release version and commits it. 5. Creates the RC tag, for example `apache-parquet-1.18.0-rc0`. -6. Deploys the artifacts to a Nexus staging repository, then closes and verifies it. +6. Deploys the artifacts to a Nexus staging repository. Then it closes and verifies the repository. 7. Builds and signs the source tarball, and writes its SHA-512 checksum. 8. Stages the tarball, signature, and checksum in [dist/dev/parquet](https://dist.apache.org/repos/dist/dev/parquet/). 9. Pushes the RC tag and creates a GitHub pre-release with generated release notes. -10. Writes the VOTE e-mail in the run summary. +10. Writes the VOTE e-mail to the run summary. -Write down the **Nexus staging repository ID** from the summary, for example +Record the **Nexus staging repository ID** from the summary, for example `orgapacheparquet-1234`. #### 2\. Review the pre-release notes Open the [pre-release](https://github.com/apache/parquet-java/releases) that -the workflow created. You can curate the generated notes: remove unrelated -changes (whitespace, test-only changes) and sort them to make them easier to -read. +the workflow created. You can edit the generated notes. For example, remove +unrelated changes (whitespace, test-only changes) and sort the changes to make +them easier to read. #### 3\. Send the VOTE e-mail to [dev@parquet.apache.org](mailto:dev@parquet.apache.org) Copy the VOTE e-mail from the run summary. Add a summary of the important -changes in the release, and make sure everything in the e-mail applies to -your release. +changes in the release. Verify that all of the e-mail text applies to your +release. ### If the vote fails @@ -137,20 +150,25 @@ Run **Release - Cancel RC** with these inputs: | `version` | Yes | | The release version, for example `1.18.0`. | | `rc_number` | Yes | | The RC number that failed the vote, for example `0`. | | `staging_repo_id` | Yes | | The Nexus staging repository ID from the Prepare RC summary, for example `orgapacheparquet-1234`. | -| `allow_description_mismatch` | No | Cleared | Skip the check that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when the description was changed by hand. | -| `dry_run` | No | Selected | Print each command without running it. | +| `allow_description_mismatch` | No | Cleared | Do not verify that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when someone changed the description by hand. | +| `dry_run` | No | Selected | Print each command and do not run it. | -Before it drops the staging repository, the workflow verifies that the -repository belongs to `org.apache.parquet`, is closed, contains the release -version, and has the expected description. +Before the workflow drops the staging repository, it verifies that the +repository: -The workflow drops the Nexus staging repository, removes the RC from -`dist/dev/parquet`, and writes the vote result e-mail in the run summary. Fill -in the reason the vote failed and send the e-mail to the dev list. +- Belongs to `org.apache.parquet`. +- Is closed. +- Contains the release version. +- Has the expected description. -The RC tag and the GitHub pre-release stay in place, so the RC number is not -used again. After the issues are fixed, run Prepare RC again; it uses the next -RC number. +The workflow drops the Nexus staging repository and removes the RC from +`dist/dev/parquet`. It also writes the vote result e-mail to the run summary. +Add the reason that the vote failed to the e-mail. Then send the e-mail to the +dev list. + +The RC tag and the GitHub pre-release stay in place, so no later RC uses the +same RC number. After you fix the issues, run Prepare RC again. It uses the +next RC number. ### Publishing after the vote passes @@ -166,21 +184,25 @@ dev list with the vote counts. | `version` | Yes | | The release version, for example `1.18.0`. | | `rc_number` | No | Latest RC | The RC number that passed the vote. It must be the latest RC for the version. | | `staging_repo_id` | Yes | | The Nexus staging repository ID from the Prepare RC summary, for example `orgapacheparquet-1234`. | -| `allow_description_mismatch` | No | Cleared | Skip the check that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when the description was changed by hand. | -| `dry_run` | No | Selected | Print each command without running it. | +| `allow_description_mismatch` | No | Cleared | Do not verify that the staging repository description is `Apache Parquet RC`. Use it only for recovery, when someone changed the description by hand. | +| `dry_run` | No | Selected | Print each command and do not run it. | + +Before it changes anything, the workflow verifies that the staging repository: + +- Belongs to `org.apache.parquet`. +- Is closed. +- Contains the release version. +- Has the description `Apache Parquet RC`. -Before it changes anything, the workflow verifies that the staging repository -belongs to `org.apache.parquet`, is closed, contains the release version, and -has the description `Apache Parquet RC`. It also checks out the -`parquet-X.Y.x` branch and verifies that its head is the RC commit. The -workflow then: +The workflow also checks out the `parquet-X.Y.x` branch and verifies that the +head of the branch is the RC commit. Then the workflow: 1. Creates the final release tag, for example `apache-parquet-1.18.0`, on the RC commit. 2. Releases the Nexus staging repository to Maven Central. 3. Pushes the release tag and creates the GitHub release. -4. Sets the next development version, for example `1.18.1-SNAPSHOT`, on the - release branch and pushes it. -5. Writes the remaining manual steps and the ANNOUNCE e-mail in the run summary. +4. Sets the next development version on the release branch, for example + `1.18.1-SNAPSHOT`, and pushes it. +5. Writes the remaining manual steps and the ANNOUNCE e-mail to the run summary. #### 3\. Move the release on dist.apache.org (PMC member) @@ -188,8 +210,9 @@ The run summary has a block of `svn` commands for the release. A PMC member copies the block and runs it with their own SVN credentials. The commands: - Move the RC from `dist/dev/parquet` to `dist/release/parquet`. -- Remove older patch releases of the same minor version that the new release - replaces. Releases of other minor versions are not changed. +- Remove the older patch releases of the same minor version that the new + release replaces. The commands do not change releases of other minor + versions. For example, for 1.14.3: @@ -205,21 +228,23 @@ Removed releases stay available on [archive.apache.org](https://archive.apache.o #### 4\. Update parquet.apache.org -Update the downloads page on parquet.apache.org and add a release blog post. -The run summary has a template for the blog post. Instructions for updating -the site are on the [contribution page](https://parquet.apache.org/docs/contribution-guidelines/contributing/). +Update the downloads page on parquet.apache.org. Add a release blog post. The +run summary has a template for the blog post. The +[contribution page](https://parquet.apache.org/docs/contribution-guidelines/contributing/) +tells you how to update the site. #### 5\. Send the ANNOUNCE e-mail to [announce@apache.org](mailto:announce@apache.org) and the dev list Copy the ANNOUNCE e-mail from the run summary. The e-mail links to the -downloads page, so send it after the release is on -[downloads.apache.org](https://downloads.apache.org/parquet/) and the site is updated. +downloads page. Send it after the release is on +[downloads.apache.org](https://downloads.apache.org/parquet/) and after you +update the site. -#### 6\. Update parquet-format with feature enablement guidance +#### 6\. Update the feature recommendations in parquet-format -The recommendations for other feature enablement is generally tied to releases of -parquet-java (details are in the parquet-format repo). As releases are made the -specification should be updated to indicate the recommended dates for when a new +Recommendations about when to enable features are usually related to +parquet-java releases. The parquet-format repository has the details. After +each release, update the specification with the recommended date when each new feature may be enabled. ### Running the release scripts locally @@ -233,28 +258,30 @@ for details. ### Release Cadence -Provided enough volunteers are available the Parquet community aims to have -releases on a quarterly basis (Targets months are January, April, July and -October). If a new major version is necessary it will be targetted for the -October release. +If enough volunteers are available, the Parquet community aims to release +every quarter. The target months are January, April, July, and October. If a +new major version is necessary, the community targets the October release for +it. ### Release Verification -The Apache Parquet Release Approval process follows the guidelines defined at the +The approval process for Apache Parquet releases follows the guidelines on the Apache Software Foundation [Release Approval](https://www.apache.org/legal/release-policy.html#release-approval) page. -For a release vote to pass, a minimum of three positive binding votes and more -positive binding votes than negative binding votes MUST be cast. -Releases may not be vetoed. Votes cast by PMC members are binding, however, -non-binding votes are greatly encouraged and a sign of a healthy project. +For a release vote to pass, it MUST get a minimum of three positive binding +votes. It MUST also get more positive binding votes than negative binding +votes. No one may veto a release. Votes from PMC members are binding. The +project strongly encourages non-binding votes, which are a sign of a healthy +project. -In order to cast a vote individuals are expected to follow the following steps. +To cast a vote, you are expected to do the steps that follow. -#### Download source package, signature file, hash file and KEYS +#### Download the source package, signature, checksum, and KEYS + +The release candidate is in `https://dist.apache.org/repos/dist/dev/parquet/`. +The name of the RC folder contains the version and the RC number. For example, +these are the files for Apache Parquet 1.15.0 RC1: -The Release candidate will be present at `https://dist.apache.org/repos/dist/dev/parquet/`. -The RC folder will depend on the version and the release candidate id. See the following example files for -Apache Parquet 1.15.0 RC 1: ``` wget https://dist.apache.org/repos/dist/dev/parquet/apache-parquet-1.15.0-rc1/apache-parquet-1.15.0.tar.gz wget https://dist.apache.org/repos/dist/dev/parquet/apache-parquet-1.15.0-rc1/apache-parquet-1.15.0.tar.gz.asc @@ -262,11 +289,12 @@ wget https://dist.apache.org/repos/dist/dev/parquet/apache-parquet-1.15.0-rc1/ap wget https://dist.apache.org/repos/dist/release/parquet/KEYS ``` -#### Verify signature and hash +#### Verify the signature and checksum + +The project recommends GnuPG. To install it: -GnuPG is recommended, which can be install by: -- `yum install gnupg` or `apt-get install gnupg` on Linux based environments. -- `brew install gnupg` on macOS environments. +- On Linux, run `yum install gnupg` or `apt-get install gnupg`. +- On macOS, run `brew install gnupg`. ``` gpg --import KEYS @@ -274,25 +302,27 @@ gpg --verify apache-parquet-1.15.0.tar.gz.asc apache-parquet-1.15.0.tar.gz sha512sum --check apache-parquet-1.15.0.tar.gz.sha512 ``` -#### Verify license header +#### Verify the license headers -Apache RAT is recommended to verify the license header, which can be dowload with the following command. +The project recommends Apache RAT to verify the license headers. To download +it, run these commands: ``` wget https://archive.apache.org/dist/creadur/apache-rat-0.16.1/apache-rat-0.16.1-bin.tar.gz tar zxvf apache-rat-0.16.1-bin.tar.gz ``` -You can check with the following command. The current command uses a regular expression to avoid raising false -positives for some files. +Run the command that follows to verify the license headers. The command uses a +regular expression to prevent false positives for some files. -The command will output a summary, the list of files with their licenses and any file that does not contain a valid license header. +The command prints a summary, a list of the files and their licenses, and each +file that does not have a valid license header. ``` java -jar apache-rat-0.16.1/apache-rat-0.16.1.jar -a -d apache-parquet-1.15.0.tar.gz -e "\w+.avsc$|\w+\-2.parquet$|.gitignore|PULL_REQUEST_TEMPLATE.md" ``` -#### Verify building and tests +#### Verify the build and the tests -Check the [building section](https://github.com/apache/parquet-java/blob/master/README.md#building) on the -[parquet-java](https://github.com/apache/parquet-java) repository. +See the [building section](https://github.com/apache/parquet-java/blob/master/README.md#building) +of the [parquet-java](https://github.com/apache/parquet-java) README.