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 2025/07/16 13:50:04 UTC
(tooling-releases-client) branch main updated: Add documentation about the release workflow
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 <se...@miscoranda.com>
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 `user-tests@tooling.apache.org` as the value here and then [consult the mailing list archives](https://lists.apache.org/list.html?user-tests@tooling.apache.org) 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 `user-tests@tooling.apache.org` as the value here and then [consult the mailing list archives](https://lists.apache.org/list.html?user-tests@tooling.apache.org) 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: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org