This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-releases-client.git
The following commit(s) were added to refs/heads/main by this push:
new 30ae9b1 Add documentation about the release workflow
30ae9b1 is described below
commit 30ae9b113d9860b5e55ede4401f861b75a3ddbe5
Author: Sean B. Palmer <[email protected]>
AuthorDate: Wed Jul 16 14:49:51 2025 +0100
Add documentation about the release workflow
---
docs/release-workflow.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++
pyproject.toml | 4 +-
uv.lock | 10 ++--
3 files changed, 136 insertions(+), 7 deletions(-)
diff --git a/docs/release-workflow.md b/docs/release-workflow.md
new file mode 100644
index 0000000..b70f49c
--- /dev/null
+++ b/docs/release-workflow.md
@@ -0,0 +1,129 @@
+# Release workflow
+
+**WARNING: The ATR client is in flux, so these instructions may become out of
date.**
+
+## Summary
+
+[Get a PAT from the Tokens page](https://release-test.apache.org/tokens) and
[install uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```
+git clone https://github.com/apache/tooling-releases-client
+cd tooling-releases-client
+uv run atr --version
+alias atr="uv run atr"
+```
+
+Now you have an `atr` command. Set a couple of required configuration values.
+
+```
+atr set asf.uid "$ASF_UID"
+atr set tokens.pat "$PAT"
+```
+
+You can now create a release.
+
+```
+atr release start your-project 0.1+test
+```
+
+Your release is in the ① COMPOSE phase.
+
+```
+atr upload your-project 0.1+test example.txt "$FILE_TO_UPLOAD"
+atr checks wait your-project 0.1+test
+atr vote start your-project 0.1+test 00002 -m "${ASF_UID}@apache.org"
+```
+
+Your release is in the ② VOTE phase.
+
+```
+atr vote resolve your-project 0.1+test passed
+```
+
+Your release is in the ③ FINISH phase.
+
+```
+atr announce your-project 0.1+test 00003 -m "${ASF_UID}@apache.org"
+```
+
+Your release is published and immutable.
+
+## Details
+
+If you run into problems with the commands above, this section may help you.
It also gives extra commands that you can try, and more information about how
the ATR client works.
+
+### Installation
+
+To test the release workflow, [log in to the `release-test` instance of ATR
using ASF OAuth](https://release-test.apache.org/) and then [go to your Tokens
page](https://release-test.apache.org/tokens). Where it says "Generate new
token" in the "Personal Access Tokens (PATs)" section, write a brief
description of your pat (e.g. "ATR client test") and then press "Generate
token". Your PAT will appear as a flash message at the top of the page; write
this down safely somewhere now, because i [...]
+
+[Install uv](https://docs.astral.sh/uv/getting-started/installation/), and
make sure you have a copy of [the ATR client
repository](https://github.com/apache/tooling-releases-client) locally. You can
then test the ATR client using the following command:
+
+```
+uv run atr --version
+```
+
+This will install the ATR client to `.venv/bin/atr` in the
`tooling-releases-client` directory. You can also add that `atr` to your
`$PATH` in various ways, or just set `alias atr="uv run atr"`. The rest of this
guide will assume that you have set this alias.
+
+### Configuration
+
+Add your ASF UID and PAT to configuration.
+
+```
+atr set asf.uid "$ASF_UID"
+atr set tokens.pat "$PAT"
+```
+
+Your `"$ASF_UID"` is just the short ASF username, e.g. `wave`, `tn`, or `sbp`
for the ASF Tooling team. The `"$PAT"` is the value you recorded earlier from
the website. If you didn't record it, you can always generate a new one as you
can have multiple PATs.
+
+The configuration path depends on your OS, but you can find it using `atr
config path`. On macOS, for example, it will be at:
+
+```
+/Users/$USER/Library/Application Support/atr/atr.yaml
+```
+
+### Compose
+
+To start a release for the `your-project` project, with release version
`0.1+test`, you would do:
+
+```
+atr release start your-project 0.1+test
+```
+
+Your release is then in the ① COMPOSE phase. You must add a file to be able to
start a vote from here. You can use `rsync` or the upload form on the ATR
website, but there is also an `atr upload` command for easier testing, and we
plan to add an `rsync` wrapper too. To upload a file at `"$FILE_TO_UPLOAD"` to
the path `example.txt` in the draft, use the following commands.
+
+```
+atr upload your-project 0.1+test example.txt "$FILE_TO_UPLOAD"
+atr checks wait your-project 0.1+test
+```
+
+To see the status of the checks here, you could run `atr checks status
your-project 0.1+test 00002`. You need to know the revision to get the status,
but we plan to make this command use the most recent revision if omitted.
+
+### Vote
+
+```
+atr vote start your-project 0.1+test 00002 -m "${ASF_UID}@apache.org"
+```
+
+Your release is in the ② VOTE phase. You must use the revision number here. We
will not support automatically finding the latest revision number in this case,
because you need to know exactly what the project's participants are voting on.
+
+Instead of your ASF email address, you can also use
`[email protected]` as the value here and then [consult the mailing
list
archives](https://lists.apache.org/[email protected]) to
check that the thread was created.
+
+### Finish
+
+```
+atr vote resolve your-project 0.1+test passed
+```
+
+Your release is in the ③ FINISH phase.
+
+```
+atr announce your-project 0.1+test 00003 -m "${ASF_UID}@apache.org"
+```
+
+Like with the vote you must know your revision to be able to announce your
release. And again, instead of your ASF email address, you can also use
`[email protected]` as the value here and then [consult the mailing
list
archives](https://lists.apache.org/[email protected]) to
check that the thread was created.
+
+### Conclusion
+
+If you are an admin you can delete your test at any time, including after
announcement, using `atr dev delete your-project 0.1+test`.
+
+For an actual example of this workflow, consult
[`cli_workflow.t`](https://github.com/apache/tooling-releases-client/blob/main/tests/cli_workflow.t)
in the ATR client test suite.
diff --git a/pyproject.toml b/pyproject.toml
index ddb0d27..c43a246 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,7 +11,7 @@ build-backend = "hatchling.build"
[project]
name = "apache-trusted-releases"
-version = "0.20250715.1943"
+version = "0.20250716.1349"
description = "ATR CLI and Python API"
readme = "README.md"
requires-python = ">=3.13"
@@ -72,4 +72,4 @@ select = [
]
[tool.uv]
-exclude-newer = "2025-07-15T19:43:00Z"
+exclude-newer = "2025-07-16T13:49:00Z"
diff --git a/uv.lock b/uv.lock
index 0c97bac..fdf144a 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2,7 +2,7 @@ version = 1
requires-python = ">=3.13"
[options]
-exclude-newer = "2025-07-15T19:43:00Z"
+exclude-newer = "2025-07-16T13:49:00Z"
[[package]]
name = "aiohappyeyeballs"
@@ -83,7 +83,7 @@ wheels = [
[[package]]
name = "apache-trusted-releases"
-version = "0.20250715.1943"
+version = "0.20250716.1349"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
@@ -538,14 +538,14 @@ wheels = [
[[package]]
name = "pytest-asyncio"
-version = "1.0.0"
+version = "1.1.0"
source = { registry = "https://pypi.org/simple"; }
dependencies = [
{ name = "pytest" },
]
-sdist = { url =
"https://files.pythonhosted.org/packages/d0/d4/14f53324cb1a6381bef29d698987625d80052bb33932d8e7cbf9b337b17c/pytest_asyncio-1.0.0.tar.gz";,
hash =
"sha256:d15463d13f4456e1ead2594520216b225a16f781e144f8fdf6c5bb4667c48b3f", size
= 46960 }
+sdist = { url =
"https://files.pythonhosted.org/packages/4e/51/f8794af39eeb870e87a8c8068642fc07bce0c854d6865d7dd0f2a9d338c2/pytest_asyncio-1.1.0.tar.gz";,
hash =
"sha256:796aa822981e01b68c12e4827b8697108f7205020f24b5793b3c41555dab68ea", size
= 46652 }
wheels = [
- { url =
"https://files.pythonhosted.org/packages/30/05/ce271016e351fddc8399e546f6e23761967ee09c8c568bbfbecb0c150171/pytest_asyncio-1.0.0-py3-none-any.whl";,
hash =
"sha256:4f024da9f1ef945e680dc68610b52550e36590a67fd31bb3b4943979a1f90ef3", size
= 15976 },
+ { url =
"https://files.pythonhosted.org/packages/c7/9d/bf86eddabf8c6c9cb1ea9a869d6873b46f105a5d292d3a6f7071f5b07935/pytest_asyncio-1.1.0-py3-none-any.whl";,
hash =
"sha256:5fe2d69607b0bd75c656d1211f969cadba035030156745ee09e7d71740e58ecf", size
= 15157 },
]
[[package]]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
