This is an automated email from the ASF dual-hosted git repository.

rzo1 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/storm.git


The following commit(s) were added to refs/heads/master by this push:
     new 678053e6b2 RELEASING.md: add the ATR (Apache Trusted Releases) path 
(#9264)
678053e6b2 is described below

commit 678053e6b28ebd07c15e0d990105a9099726ded1
Author: reiabreu <[email protected]>
AuthorDate: Wed Nov 11 19:36:19 2026 +0000

    RELEASING.md: add the ATR (Apache Trusted Releases) path (#9264)
    
    * RELEASING.md: add the ATR (Apache Trusted Releases) path
    
    Document staging, voting, publishing and announcing through ATR, on the
    website or from the atr command line. The SVN steps stay as the alternative.
    Release managers must pick one path per release and not mix them.
    
    Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
    
    * Add the ATR vote email template and document how to use it
    
    ATR can fetch the vote email template from a URL. The new
    dev-tools/atr/start-vote-template.txt is the Storm template, built from 
ATR's
    default with the Storm specifics from RELEASING.md (Nexus staging 
repository,
    full and lite binaries, how to vote). It is excluded from RAT because it is 
sent
    as an email body. RELEASING.md explains the one-time ATR setting and how the
    website form and the command line use it.
    
    Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
    
    * Move the ATR vote email template to its own pull request
    
    RELEASING.md keeps pointing at dev-tools/atr/start-vote-template.txt, which 
is
    added by that pull request.
    
    Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
    
    * Keep the SVN email templates in RELEASING.md as they were
    
    Restore the original dist.apache.org URLs in the SVN vote and cancel 
templates.
    ATR users get their vote email from dev-tools/atr/start-vote-template.txt.
    
    Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
    
    * Document the ATR announcement template and the download path suffix
    
    - One-time setup: the announce template URL and subject, and the default 
download
      path suffix (apache-storm-{{VERSION}}), without which ATR publishes flat 
into dist/release/storm/.
    - Publish step: check the suffix before publishing, and how to fix it 
afterwards.
    - Announce step: the ATR form and command line use 
dev-tools/atr/announce-template.txt.
    
    Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
    
    ---------
    
    Co-authored-by: Claude Sonnet 5.5 <[email protected]>
---
 RELEASING.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 165 insertions(+), 20 deletions(-)

diff --git a/RELEASING.md b/RELEASING.md
index d82eebd37e..5b1ca14d58 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -17,7 +17,7 @@ Apache Storm follows the basic idea of [Semantic 
Versioning](https://semver.org/
 
 - We strongly encourage you to read the [Apache release signing 
page](https://www.apache.org/dev/release-signing.html), the [release 
distribution 
page](https://www.apache.org/dev/release-distribution.html#sigs-and-sums), as 
well as the [release 
publishing](https://www.apache.org/dev/release-publishing), [release 
policy](https://www.apache.org/legal/release-policy.html) and [Maven 
publishing](https://infra.apache.org/publishing-maven-artifacts.html) pages. 
ASF has common guidelines that a [...]
 - Ensure you can log in to https://repository.apache.org. You should use your 
Apache ID username and password.
-- Install a SVN client, and ensure you can access the 
https://dist.apache.org/repos/dist/dev/storm/ and 
https://dist.apache.org/repos/dist/release/storm/ repositories. You should be 
able to access these with your Apache ID username and password.
+- Install a SVN client, and ensure you can access the 
https://dist.apache.org/repos/dist/dev/storm/ and 
https://dist.apache.org/repos/dist/release/storm/ repositories. You should be 
able to access these with your Apache ID username and password. You need this 
to maintain the KEYS file, and to stage and publish the release through SVN. If 
you stage and publish through ATR instead, see [Using Apache Trusted Releases 
(ATR)](#using-atr).
 - During the release phase, artifacts will be uploaded to 
https://repository.apache.org. This means Maven needs to know your LDAP 
credentials. It is recommended that you use Maven's mechanism for [password 
encryption](https://maven.apache.org/guides/mini/guide-encryption.html). Please 
configure this in your `${user.home}/.m2/settings.xml`:
   
 ```xml
@@ -57,8 +57,78 @@ Apache Storm follows the basic idea of [Semantic 
Versioning](https://semver.org/
 If you are setting up a new MINOR version release, create a new branch based 
on `master` branch, e.g. `2.7.x-branch`. Then on master branch, set the version 
to a higher MINOR version (with SNAPSHOT), e.g. `mvn versions:set 
-DnewVersion=2.8.0-SNAPSHOT -P dist,rat,externals,examples`.
 In this way, you create a new release line and then you can create PATCH 
version releases from it, e.g. `2.7.1`.
 
+<a id="using-atr"></a>
+## Using Apache Trusted Releases (ATR)
+
+[ATR](https://releases.apache.org/) is the ASF platform for staging, voting on 
and publishing releases. It replaces the `dist/dev`
+staging area, sends the vote and announcement emails on your behalf, and 
publishes the approved files to `dist/release`. It is currently
+in beta. ATR does **not** build or sign the artifacts and does **not** publish 
to Maven Central: building, signing and the Nexus staging
+repository work as described in the steps below.
+
+> **Pick one path for each release, ATR or SVN, and never mix them.** The two 
paths diverge at staging (step 6 of
+> [Setting up a vote](#setting-up-a-vote)), at the vote email (step 11), and 
again when publishing and announcing after the vote.
+> Decide before you start and follow only the matching variant in every step. 
Mixing them, for example staging in `dist/dev` and also
+> starting the release in ATR, or running `svn mv` into `dist/release` while 
ATR holds the release, leaves two diverging copies of the
+> release candidate. Inside ATR you are free to switch between the website and 
the command line.
+
+Every ATR step can be done either on the **website** 
(https://releases.apache.org, log in with your ASF account) or from the
+**command line** with the `atr` client. The steps below give both. Voting 
still happens on [email protected],
+and only votes from the Storm PMC are binding. Staging and publishing through 
SVN without ATR still works; the SVN variants are marked in the steps below.
+
+### One-time setup
+
+1. Register for the ASF multi-factor authentication at https://mfa.apache.org/.
+2. You must be a PMC member, or be designated as a release manager by a PMC 
member on the Storm committee page in ATR.
+3. Make sure ATR knows your OpenPGP signing key. By default ATR imports the 
Storm KEYS file from SVN, so adding your key to KEYS as described in 
[Preparation](#preparation)
+   is enough. You can also add the key at https://releases.apache.org/keys. 
New keys must be RSA of at least 4096 bits, or Ed25519 / ECDSA (P-256 or 
stronger); DSA keys are rejected.
+4. Get the credentials for the way you upload files:
+   - website: nothing more than your ASF login;
+   - `rsync`: add an SSH **public** key at https://releases.apache.org/keys. 
This is a different key from your OpenPGP key. You connect as your ASF UID on 
port 2222;
+   - command line: create a personal access token at 
https://releases.apache.org/tokens (it expires after 180 days).
+5. To use the command line, install the client (it needs 
[uv](https://docs.astral.sh/uv/getting-started/installation/)) and sign in:
+
+   ```bash
+   uv tool install "apache-trusted-releases @ 
git+https://github.com/apache/tooling-releases-client";
+   atr set asf.uid <your-asf-uid>
+   atr set tokens.pat
+   atr jwt refresh
+   ```
+
+   `atr set tokens.pat` asks for the token without echoing it. Run `atr 
--help` or `atr docs` for the full command reference. The client is not yet 
stable, so do not use it in unattended scripts.
+6. Log in on the website and check that the Storm project is listed. Its 
project key is `storm`.
+7. The vote email template lives in this repository, in 
[`dev-tools/atr/start-vote-template.txt`](dev-tools/atr/start-vote-template.txt).
 Once, in the project settings in ATR
+   (**Vote** tab), set **Start vote template URL** to
+   
`https://raw.githubusercontent.com/apache/storm/master/dev-tools/atr/start-vote-template.txt`.
 ATR fetches the template whenever the vote form is shown, so changes to
+   the file in `master` apply to the next vote. The file uses ATR's 
`{{VARIABLES}}`, listed under **Available template variables** on the same 
settings page.
+   It is sent as the body of the email, so it must not carry a license header.
+8. The announcement email template is in 
[`dev-tools/atr/announce-template.txt`](dev-tools/atr/announce-template.txt). 
In the same project settings, set
+   **Announce release template URL** to
+   
`https://raw.githubusercontent.com/apache/storm/master/dev-tools/atr/announce-template.txt`,
 and **Announce release subject** to
+   `[ANNOUNCE] Apache {{PROJECT_NAME}} {{VERSION}} Released`. The blog post 
line has `[YEAR]`, `[MONTH]`, `[DAY]` and `[VERSION-WITHOUT-DOTS]` to fill in 
when you send,
+   for example `https://storm.apache.org/2026/09/12/storm310-released.html` 
for 3.1.0.
+9. In the project settings, set **Default download path suffix** to 
`apache-storm-{{VERSION}}`. It pre-fills the publish path. Storm is the 
top-level project of its committee,
+   so with the field empty ATR publishes the files straight into 
`dist/release/storm/`, and not into `apache-storm-x.x.x/` as every earlier 
release did.
+
+### ATR operations at a glance
+
+| Step | Website | Command line (`x.x.x` is the release version) |
+|---|---|---|
+| Start the release | **Draft → Candidates → Start a new release** | `atr 
release start storm x.x.x` |
+| Upload the files | Compose page → **Upload files** (browser, `svn` or 
`rsync`) | `atr rsync storm x.x.x ./candidate/` or `atr upload ...` |
+| Review the checks | Compose page | `atr check 
wait\|status\|blockers\|concerns storm x.x.x` |
+| Start the vote | Compose page → **Start voting** | `atr vote start storm 
x.x.x -m [email protected] --subject ... --body-file vote.txt` |
+| Read the tally | Vote page | `atr vote tabulate storm x.x.x` |
+| Resolve the vote | Vote page → **Resolve vote** (the only way for email 
votes) | not available for email votes |
+| Record the Maven Central release | Finish page → **Verify a third-party 
distribution** | `atr distribution record storm x.x.x MAVEN org.apache.storm 
<artifactId> x.x.x` |
+| Publish to `dist/release` | Finish page → **Publish to ASF Distribution 
Area** | add `--auto-publish` to `vote start` (PMC members only) |
+| Announce | Finish page → **Announce** | `atr announce storm x.x.x -m 
[email protected] --body-file announce.txt` |
+
+<a id="setting-up-a-vote"></a>
 ## Setting up a vote
 
+> **Choose your path first: ATR or SVN, not both.** Steps marked **ATR** and 
**SVN** are alternatives. Follow the variant of the path you chose and skip the 
other.
+> See [Using Apache Trusted Releases (ATR)](#using-atr).
+
 1. Checkout to the branch to be released.
 
 2. <a id="rc-maven-release"></a>Run `mvn release:prepare -P 
dist,rat,externals,examples` followed by `mvn release:perform -P 
dist,rat,externals,examples`.
@@ -112,7 +182,11 @@ In this way, you create a new release line and then you 
can create PATCH version
    > omits them. Both must be signed, checksummed and staged for the release 
candidate.
    > See [Storm lite distribution](#storm-lite-distribution) below.
 
-6. <a id="rc-svn-dir"></a>Create a directory in the dist svn repo for the 
release candidate: 
https://dist.apache.org/repos/dist/dev/storm/apache-storm-x.x.x-rcx
+6. <a id="rc-svn-dir"></a>Decide where the release candidate is staged.
+
+   - **ATR:** start the release, on the website (**Draft → Candidates → Start 
a new release**) or from the command line: `atr release start storm x.x.x`.
+     A failed vote returns the release to the Compose phase, so the version 
stays the same and the `rcN` counter only appears in the vote email.
+   - **SVN:** create a directory in the dist svn repo for the release 
candidate: https://dist.apache.org/repos/dist/dev/storm/apache-storm-x.x.x-rcx
 
 7. Before generating the release notes, please double check if all merged pull 
requests for the version being released are assigned the milestone in question. 
They won't be placed in the release notes otherwise.
 
@@ -137,7 +211,7 @@ In this way, you create a new release line and then you can 
create PATCH version
    - Click on the milestone you want to create release notes for.
    - Look at the URL in your browser. It will look like this: 
`https://github.com/apache/storm/milestone/40`, where the last number is the 
milestone ID.
 
-9. Move the release files from the [tag checkout](#rc-checkout-tag), 
[checksums](#rc-checksums) and [release notes](#rc-release-notes) steps to the 
[dist svn directory](#rc-svn-dir). Example of the set of files:
+9. Move the release files from the [tag checkout](#rc-checkout-tag), 
[checksums](#rc-checksums) and [release notes](#rc-release-notes) steps to the 
[staging location](#rc-svn-dir): a local directory such as `./candidate/` for 
ATR, or the dist svn directory for SVN. Example of the set of files:
 
    ```
    apache-storm-2.8.3-src.tar.gz         apache-storm-2.8.3-src.zip         
apache-storm-2.8.3.tar.gz         apache-storm-2.8.3.zip         
RELEASE_NOTES.html
@@ -148,17 +222,52 @@ In this way, you create a new release line and then you 
can create PATCH version
    apache-storm-2.8.3-lite.tar.gz.sha512 apache-storm-2.8.3-lite.zip.sha512
    ```
 
-10. Add and commit the files to SVN. This makes them available in the Apache 
staging repo.
+10. Upload or commit the files.
 
-    ```bash
-    cd <your-svn-checkout>/apache-storm-x.x.x-rcx
-    svn add *
-    svn commit -m "Add release candidate apache-storm-x.x.x-rcx"
-    ```
+    - **ATR:** upload on the website (Compose page → **Upload files**, by 
browser, `svn` or `rsync`) or from the command line:
+
+      ```bash
+      atr rsync storm x.x.x ./candidate/
+      ```
+
+      `rsync` needs an SSH public key registered at 
https://releases.apache.org/keys, and connects as your ASF UID on port 2222. 
Then wait for the checks
+      on the Compose page, or run:
+
+      ```bash
+      atr check wait storm x.x.x --timeout 300
+      atr check status storm x.x.x --verbose
+      atr check blockers storm x.x.x --members
+      atr check concerns storm x.x.x --members
+      ```
+
+      Fix every blocker (re-sign, re-checksum and re-upload the affected 
files). Read every concern: you acknowledge the remaining ones when you start 
the vote.
+      ATR also asks for the full 40-character commit the sources were built 
from, which is `git rev-parse vx.x.x^{commit}`.
+      Expect the concern `RELEASE_NOTES.html: Unknown top level file`: ATR 
only accepts `CHANGES`, `LICENSE`, `NOTICE`, `README` and `SECURITY` (with an 
empty, `.adoc`, `.md`, `.rst` or `.txt` suffix) at the top level of a candidate.
+    - **SVN:** add and commit the files to SVN. This makes them available in 
the Apache staging repo.
+
+      ```bash
+      cd <your-svn-checkout>/apache-storm-x.x.x-rcx
+      svn add *
+      svn commit -m "Add release candidate apache-storm-x.x.x-rcx"
+      ```
 
 11. Start the VOTE thread. The vote should follow the [ASF voting 
process](https://www.apache.org/foundation/voting.html).
 
-    *Sample template, sent to [email protected]:*
+    - **ATR:** start the vote on the website (Compose page → **Start voting**) 
or from the command line. ATR sends the email to the list you choose, in your 
name.
+      On the website the form is filled in from 
[`dev-tools/atr/start-vote-template.txt`](dev-tools/atr/start-vote-template.txt)
 (see [One-time setup](#using-atr)),
+      with the ATR variables replaced. Replace `[REPO_NUM]` with the number of 
the Nexus staging repository, review the text, and send. This is the easier way 
for Storm,
+      because ATR fills in the variables for you.
+      From the command line, write the whole email body yourself, with every 
value filled in (use the template file as the starting point), and pass the 
subject line separately:
+
+      ```bash
+      atr vote start storm x.x.x -m [email protected] -d 72 --subject 
"[VOTE] Release Apache Storm x.x.x (rcN)" --body-file vote.txt
+      ```
+
+      Add `--concerns-noted <keys>` to acknowledge the remaining concerns. 
`--auto-publish` (PMC members only) publishes the files as soon as the vote is 
resolved;
+      leave it out if you want to control when that happens.
+    - **SVN:** send the email yourself, using the sample template below.
+
+    *Sample template for an SVN vote, sent to [email protected]:*
 
     ```
     Subject: [VOTE] Release Apache Storm [VERSION] (rcN)
@@ -228,7 +337,13 @@ from Maven Central (or an internal mirror configured in 
`settings.xml`).
 
 ## Releasing if the vote succeeds
 
-0. Announce the results. Use the following template:
+> Continue on the path you chose when you [set up the 
vote](#setting-up-a-vote): the **ATR** and **SVN** variants below are 
alternatives.
+
+0. Announce the results.
+
+   - **ATR:** check ATR's tally against the vote thread, then resolve the vote 
on the vote page (**Resolve vote**; this is the only way to resolve an email 
vote).
+     `atr vote tabulate storm x.x.x` shows the tally from the command line. 
ATR emails the outcome to the list, and a passing vote moves the release to the 
Finish phase.
+   - **SVN:** use the following template:
 
    ```text
    Subject: [VOTE][RESULT] Storm [VERSION] Release Candidate [N]
@@ -251,18 +366,32 @@ from Maven Central (or an internal mirror configured in 
`settings.xml`).
    [RELEASE MANAGER NAME]
    ```
 
-1. Move the release candidate to the release directory and publish it:
+1. Publish the release candidate to the release directory.
 
-   ```bash
-   svn mv https://dist.apache.org/repos/dist/dev/storm/apache-storm-x.x.x-rcx \
-          https://dist.apache.org/repos/dist/release/storm/apache-storm-x.x.x \
-          -m "Publish Apache Storm x.x.x release"
-   ```
+   - **ATR:** on the Finish page use **Publish to ASF Distribution Area**, and 
set the download path suffix to `apache-storm-x.x.x` so the files end up where 
they always have.
+     The field is pre-filled if you did the [One-time setup](#using-atr); 
check it before you publish. If it is empty the files land directly in 
`dist/release/storm/`, and you
+     have to move them into `apache-storm-x.x.x/` with one `svn mv` commit 
afterwards.
+     If you started the vote with `--auto-publish`, ATR has already done this 
when the vote was resolved.
+   - **SVN:**
 
-   This will make the release artifacts available on dist.apache.org and the 
artifacts will start replicating to mirrors.
+     ```bash
+     svn mv 
https://dist.apache.org/repos/dist/dev/storm/apache-storm-x.x.x-rcx \
+            
https://dist.apache.org/repos/dist/release/storm/apache-storm-x.x.x \
+            -m "Publish Apache Storm x.x.x release"
+     ```
+
+   Either way, this will make the release artifacts available on 
dist.apache.org and the artifacts will start replicating to mirrors.
 
 2. Go to https://repository.apache.org and release the staging repository.
 
+   **ATR:** then record the Maven Central release in ATR, on the Finish page 
(**Verify a third-party distribution**) or from the command line, once per 
artifact:
+
+   ```bash
+   atr distribution record storm x.x.x MAVEN org.apache.storm <artifactId> 
x.x.x
+   ```
+
+   ATR can require this before it lets you announce.
+
 3. Wait at least 24 hrs. for the mirrors to catch up.
 
 4. Check out the [storm-site](https://github.com/apache/storm-site) 
repository, and follow the README to generate release specific documentation for
@@ -272,6 +401,7 @@ from Maven Central (or an internal mirror configured in 
`settings.xml`).
 5. Update `doap_Storm.rdf` with the new release version.
 
 6. Delete any outdated releases from the 
https://dist.apache.org/repos/dist/release/storm/ repository. See [when to 
archive](https://www.apache.org/legal/release-policy.html#when-to-archive).
+   With ATR, you can instead archive the superseded release from its page in 
ATR.
 
 7. Delete any outdated releases from the storm-site releases directory, and 
republish the site.
 
@@ -281,7 +411,17 @@ from Maven Central (or an internal mirror configured in 
`settings.xml`).
 
 10. Create a new release for [Storm 
Docker](https://github.com/apache/storm-docker). Example of a version release 
[here](https://github.com/apache/storm-docker/commit/177a1534bf910c2271845f4eaedef7c040559fbc).
 After that is done, a PR to 
[docker-library](https://github.com/docker-library/official-images) must be 
submitted, so that the new docker-storm version is officially released. Example 
of such a PR is 
[here](https://github.com/docker-library/official-images/pull/21525#issuecomment-4
 [...]
 
-11. Post, promote, celebrate. ;) Announce the new release to 
[email protected], [email protected], and [email protected] (you must 
use your @apache.org email to post to [email protected]), using the following 
template:
+11. Post, promote, celebrate. ;) Announce the new release to 
[email protected], [email protected], and [email protected] (you must 
use your @apache.org email to post to [email protected]), using the following 
template.
+
+    With ATR, you can send the announcement from ATR once the files have 
reached the download servers: on the Finish page (**Announce**) or from the 
command line.
+    On the website the form is filled in from 
[`dev-tools/atr/announce-template.txt`](dev-tools/atr/announce-template.txt) 
(see [One-time setup](#using-atr)); fill in the blog post line and send.
+    From the command line, use that file as the body, with every 
`{{VARIABLE}}` filled in (`--cc` and `--bcc` add other permitted lists):
+
+    ```bash
+    atr announce storm x.x.x -m [email protected] --body-file announce.txt
+    ```
+
+    With SVN, send it yourself.
 
     ```text
     Subject: [ANNOUNCE] Apache Storm [VERSION] Released
@@ -330,7 +470,10 @@ from Maven Central (or an internal mirror configured in 
`settings.xml`).
 
 1. Go to https://repository.apache.org and drop the staging repository.
 
-2. Delete the staged distribution files from 
https://dist.apache.org/repos/dist/dev/storm/.
+2. Clean up the staged files.
+
+   - **ATR:** nothing to delete in `dist`. Resolve the vote as failed on the 
vote page; the release returns to the Compose phase, where you upload the next 
candidate.
+   - **SVN:** delete the staged distribution files from 
https://dist.apache.org/repos/dist/dev/storm/.
 
 3. Delete the git tag.
 
@@ -352,6 +495,8 @@ We encourage everyone to review and vote on a release 
candidate to make an Apach
 Below is a checklist that one could do to review a release candidate. 
 Please note this list is not exhaustive and only includes some of the common 
steps. Feel free to add your own tests.
 
+0. Get the candidate files from the link in the vote email: a 
`dist.apache.org` directory for an SVN vote, or the vote page for an ATR vote, 
which also shows the check results. On the ATR vote page anyone can download 
the files in the browser or with `curl`; the ZIP download and `rsync` need a 
login.
+
 1. Verify files such as *.asc, *.sha512; some scripts are available under 
`dev-tools/rc` to help with it;
 2. <a id="vote-build-distribution"></a>Build Apache Storm source code and run 
unit tests, create an Apache Storm distribution;
 3. Set up a standalone cluster using apache-storm-xxx.zip, 
apache-storm-xxx.tar.gz, the Apache Storm distribution created in [the build 
step](#vote-build-distribution), separately;

Reply via email to