You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by sb...@apache.org on 2026/05/28 19:04:43 UTC
(tooling-trusted-releases) 01/01: Document how to move files in SVN dist for publication
This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch altera
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
commit 25d2a9c4acf1a1e3f61f82b16a189ab222c20a23
Author: Sean B. Palmer <se...@miscoranda.com>
AuthorDate: Thu May 28 20:03:46 2026 +0100
Document how to move files in SVN dist for publication
---
atr/docs/index.md | 1 +
atr/docs/promoting-to-release.md | 109 +++++++++++++++++++++++++++++++++++++++
atr/docs/running-the-server.md | 2 +-
atr/docs/sbom-workflows.md | 2 +-
atr/docs/user-guide.md | 1 +
5 files changed, 113 insertions(+), 2 deletions(-)
diff --git a/atr/docs/index.md b/atr/docs/index.md
index 4265112e..7693fe89 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -14,6 +14,7 @@ NOTE: This documentation is a work in progress.
* `2.4.` [License checks](license-checks)
* `2.5.` [Trusted Publishing](trusted-publishing)
* `2.6.` [SBOM workflows](sbom-workflows)
+ * `2.7.` [Promoting to release](promoting-to-release)
* `3.` [Developer guide](developer-guide)
* `3.1.` [Running the server](running-the-server)
* `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/promoting-to-release.md b/atr/docs/promoting-to-release.md
new file mode 100644
index 00000000..56ce02ae
--- /dev/null
+++ b/atr/docs/promoting-to-release.md
@@ -0,0 +1,109 @@
+# 2.7. Promoting to release
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: `2.6.` [SBOM workflows](sbom-workflows)
+
+**Next**: `3.1.` [Running the server](running-the-server)
+
+**Sections**:
+
+* [Overview](#overview)
+* [Prerequisites](#prerequisites)
+* [Moving the files](#moving-the-files)
+* [Verifying the move](#verifying-the-move)
+* [Removing superseded releases](#removing-superseded-releases)
+* [The KEYS file](#the-keys-file)
+
+## Overview
+
+When the ATR workflow completes, i.e. when the vote is resolved and the release announced, ATR commits the approved artifacts to its own area of the Apache distribution SVN repository:
+
+* TLP: `https://dist.apache.org/repos/dist/atr/<committee>/`
+* Podling: `https://dist.apache.org/repos/dist/atr/incubator/<committee>/`
+
+Files in `/dist/atr/` are **not mirrored** by the Apache distribution mirror network and are not considered official releases. To make the release official and available on `downloads.apache.org` and the mirror network, a project committer with write permissions on the destination must move the files into the canonical release area:
+
+* TLP: `https://dist.apache.org/repos/dist/release/<committee>/`
+* Podling: `https://dist.apache.org/repos/dist/release/incubator/<committee>/`
+
+The move is a manual SVN step performed once per release. ATR does not do it for you yet because automatic publishing to SVN is currently in testing, so we use `/dist/atr/` instead of `/dist/release/`. In future, ATR will do this for you.
+
+## Prerequisites
+
+You need a working `svn` client and your ASF committer credentials. The destination path under `/dist/release/` must be writable by your ASF user. You can check committee membership on [the Whimsy roster](https://whimsy.apache.org/roster/).
+
+Before you start, confirm what ATR published and where. List the source directory with:
+
+```shell
+svn ls https://dist.apache.org/repos/dist/atr/<committee>/
+```
+
+**Podling note**: For a podling, prefix the committee path with `incubator/`. Podlings replace `release/<committee>/` with `release/incubator/<committee>/` everywhere below. The source paths under `atr/incubator/<committee>/` follow the same shape. Incubator policy additionally requires the IPMC to have voted on the release before promotion; the PPMC vote that ATR records is not sufficient on its own.
+
+You should also decide the destination layout. Two common conventions exist. The first is a flat layout that matches what ATR produced, where files sit directly under `release/<committee>/`. The second is a per version subdirectory, where files live at `release/<committee>/<version>/`_file_. Most TLPs use the per version layout. Stick to whatever your project has used for previous releases, which you can check with:
+
+```shell
+svn ls https://dist.apache.org/repos/dist/release/<committee>/
+```
+
+## Moving the files
+
+There are two general ways to perform the move. Choose based on whether the destination layout matches the source.
+
+### Option A: flat to flat
+
+If the destination layout matches the source layout, a single `svn move` from URL to URL moves every artifact for one version in one revision. List each source URL explicitly so that unrelated files in `/dist/atr/<committee>/`, e.g. artifacts from other versions, are left alone:
+
+```shell
+svn move -m "Promote <committee> <version> to release" \
+ https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz \
+ https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz.asc \
+ https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz.sha256 \
+ https://dist.apache.org/repos/dist/release/<committee>/
+```
+
+Multiple sources moved to a single destination directory commit atomically as one revision.
+
+### Option B: flat to per version subdirectory
+
+If you need to place files under a new _version_ directory, or you need to rename anything in flight, use `svnmucc`. This is the _Multiple URL Command Client_, and it ships with the standard `subversion` package. It can performs many URL operations in a single atomic revision:
+
+```shell
+svnmucc -m "Promote <committee> <version> to release" \
+ mkdir https://dist.apache.org/repos/dist/release/<committee>/<version> \
+ mv https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz \
+ https://dist.apache.org/repos/dist/release/<committee>/<version>/<artifact>.tar.gz \
+ mv https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz.asc \
+ https://dist.apache.org/repos/dist/release/<committee>/<version>/<artifact>.tar.gz.asc \
+ mv https://dist.apache.org/repos/dist/atr/<committee>/<artifact>.tar.gz.sha256 \
+ https://dist.apache.org/repos/dist/release/<committee>/<version>/<artifact>.tar.gz.sha256
+```
+
+Drop the `mkdir` line if the version directory already exists. `svnmucc` will refuse with error `E160020` if it does.
+
+## Verifying the move
+
+After the commit, list both directories and confirm that the artifacts have moved:
+
+```shell
+svn ls https://dist.apache.org/repos/dist/release/<committee>/
+svn ls https://dist.apache.org/repos/dist/atr/<committee>/
+```
+
+The artifacts should appear under `release/` and be gone from `atr/`. The files should soon become visible at `https://downloads.apache.org/<committee>/...`.
+
+## Removing superseded releases
+
+Apache distribution policy is that `/dist/release/` should hold only the current release of each line, with everything older moved to `archive.apache.org`. Releases committed to `/dist/release/` are picked up by the archive automatically, so you do not have to copy them there yourself. You do, however, have to delete the superseded ones:
+
+```shell
+svn rm -m "Remove superseded <committee> <previous-version>" \
+ https://dist.apache.org/repos/dist/release/<committee>/<previous-version>
+```
+
+Do this as a separate commit, after promotion, once you have verified that the new release is reachable.
+
+## The KEYS file
+
+The `KEYS` file lives at `https://dist.apache.org/repos/dist/release/<committee>/KEYS` and is managed independently of any individual release. ATR does not publish it. If a new signer's key is used for this release, update `KEYS` from your local SVN checkout in a separate commit before users begin verifying artifacts.
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index aa83594d..7d53842b 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: `2.6.` [SBOM workflows](sbom-workflows)
+**Prev**: `2.7.` [Promoting to release](promoting-to-release)
**Next**: `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/sbom-workflows.md b/atr/docs/sbom-workflows.md
index 34490b2b..7fda5d0c 100644
--- a/atr/docs/sbom-workflows.md
+++ b/atr/docs/sbom-workflows.md
@@ -4,7 +4,7 @@
**Prev**: `2.5.` [Trusted Publishing](trusted-publishing)
-**Next**: `3.1.` [Running the server](running-the-server)
+**Next**: `2.7.` [Promoting to release](promoting-to-release)
**Sections**:
diff --git a/atr/docs/user-guide.md b/atr/docs/user-guide.md
index 838dcab3..d48aa0f0 100644
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -14,6 +14,7 @@
* `2.4.` [License checks](license-checks)
* `2.5.` [Trusted Publishing](trusted-publishing)
* `2.6.` [SBOM workflows](sbom-workflows)
+* `2.7.` [Promoting to release](promoting-to-release)
**Sections**:
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org