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-trusted-release.git
The following commit(s) were added to refs/heads/main by this push:
new 9800c2c Document some example test user flows
9800c2c is described below
commit 9800c2cdb20ec7630bb27c4e71fb7900064d564c
Author: Sean B. Palmer <[email protected]>
AuthorDate: Tue Sep 9 17:25:13 2025 +0100
Document some example test user flows
---
atr/routes/projects.py | 6 ++--
atr/storage/writers/announce.py | 2 ++
docs/test-user-flows.html | 45 ++++++++++++++++++++++++++
docs/test-user-flows.md | 71 +++++++++++++++++++++++++++++++++++++++++
4 files changed, 121 insertions(+), 3 deletions(-)
diff --git a/atr/routes/projects.py b/atr/routes/projects.py
index 9c87c8c..c2acecc 100644
--- a/atr/routes/projects.py
+++ b/atr/routes/projects.py
@@ -537,10 +537,10 @@ async def _policy_edit(
util.unwrap(policy_form.github_vote_workflow_path.data)
)
release_policy.mailto_addresses =
[util.unwrap(policy_form.mailto_addresses.data)]
- _set_default_min_hours(policy_form, project, release_policy) #
TODO
+ _set_default_min_hours(policy_form, project, release_policy)
release_policy.pause_for_rm =
util.unwrap(policy_form.pause_for_rm.data)
release_policy.release_checklist =
util.unwrap(policy_form.release_checklist.data)
- _set_default_start_vote_template(policy_form, project,
release_policy) # TODO
+ _set_default_start_vote_template(policy_form, project,
release_policy)
elif project.committee and project.committee.is_podling:
# The caller ensures that project.committee is not None
await quart.flash("Manual voting is not allowed for podlings.",
"error")
@@ -550,7 +550,7 @@ async def _policy_edit(
release_policy.github_finish_workflow_path = _parse_artifact_paths(
util.unwrap(policy_form.github_finish_workflow_path.data)
)
- _set_default_announce_release_template(policy_form, project,
release_policy) # TODO
+ _set_default_announce_release_template(policy_form, project,
release_policy)
release_policy.preserve_download_files =
util.unwrap(policy_form.preserve_download_files.data)
await data.commit()
diff --git a/atr/storage/writers/announce.py b/atr/storage/writers/announce.py
index 7cc67c7..3b8321e 100644
--- a/atr/storage/writers/announce.py
+++ b/atr/storage/writers/announce.py
@@ -203,6 +203,8 @@ class CommitteeMember(CommitteeParticipant):
raise storage.AccessError(f"Database updated, but error moving
files: {e!s}. Manual cleanup needed.")
# TODO: Add an audit log entry here
+ # TODO: We should consider copying the files instead of hard linking
+ # That way, we can write protect the pristine ATR files
await self.__hard_link_downloads(
committee,
finished_path,
diff --git a/docs/test-user-flows.html b/docs/test-user-flows.html
new file mode 100644
index 0000000..5b1af85
--- /dev/null
+++ b/docs/test-user-flows.html
@@ -0,0 +1,45 @@
+<h1>Test user flows</h1>
+<p>To test the ATR, here are some example command line and GitHub user
flows.</p>
+<h2>Command line</h2>
+<p>To install the <code>atr</code> command, use the <a
href="https://github.com/apache/tooling-releases-client/tree/main?tab=readme-ov-file#quick-start";>the
instructions in the client <code>README.md</code></a>, or simply use <code>uv
run atr</code> instead of <code>atr</code>.</p>
+<p><a href="https://release-test.apache.org/tokens";>Create a PAT</a> using the
UI, then store the value in <code>atr</code> configuration.</p>
+<pre><code>atr set tokens.pat "$PAT_FROM_UI"
+</code></pre>
+<p>You can view the configuration file to check that the value is set.
<strong>This will write secret values to stdout.</strong></p>
+<pre><code>atr config file
+</code></pre>
+<p>The following commands constitute roughly an entire flow, which will be
reflected in the UI. We are using <code>tooling-test-example</code> as the
project name. Don't forget to <a
href="https://release-test.apache.org/project/add/tooling";>create this or
another project</a>, or <a
href="https://release-test.apache.org/committees";>use an existing project</a>
as applicable. Use your ASF UID <code>@apache.org</code> instead of
<code>example</code>.</p>
+<pre><code>atr release start tooling-test-example 0.1+demo
+
+atr upload tooling-test-example 0.1+demo example.txt ../example.txt
+
+atr check wait tooling-test-example 0.1+demo -i 25
+
+atr check status tooling-test-example 0.1+demo
+
+atr release info tooling-test-example 0.1+demo
+
+atr vote start tooling-test-example 0.1+demo 00002 -m [email protected]
+
+atr vote resolve tooling-test-example 0.1+demo passed
+
+atr distribution record tooling-test-example 0.1+demo NPM None react 18.2.0
False False
+
+atr release info tooling-test-example 0.1+demo
+
+atr announce tooling-test-example 0.1+demo 00003 -m [email protected] -s
Subject -b Body
+</code></pre>
+<p>When finished with an example flow, it is recommended that you delete the
version.</p>
+<pre><code>atr dev delete tooling-test-example 0.1+demo
+</code></pre>
+<p>If there is ever a problem with a JWT verification, try refreshing your
JWT.</p>
+<pre><code>atr jwt refresh | wc
+</code></pre>
+<h2>GitHub actions</h2>
+<p>We use <a href="https://github.com/apache/tooling-asf-example";>the
<code>tooling-asf-example</code></a> repository to check our GitHub actions.</p>
+<p>First, <a href="https://release-test.apache.org/";>start a new release in
the ATR web UI</a>.</p>
+<p>You can then use the <a
href="https://github.com/apache/tooling-asf-example/actions/workflows/build-and-rsync-to-atr.yaml";><code>build-and-rsync-to-atr.yaml</code></a>
workflow to build Python wheel files an upload them to the ATR.</p>
+<p>Then, start a vote in the ATR web UI. This cannot be linked here because
the URL will depend on which project and version you use.</p>
+<p>Use the <a
href="https://github.com/apache/tooling-asf-example/actions/workflows/resolve-vote-on-atr.yaml";><code>resolve-vote-on-atr.yaml</code></a>
workflow to resolve the vote.</p>
+<p>Use the <a
href="https://github.com/apache/tooling-asf-example/actions/workflows/record-distribution-on-atr.yaml";><code>record-distribution-on-atr.yaml</code></a>
workflow to record an external distribution. The external distribution
<em>must exist</em> on the distribution platform, because the ATR fetches real
metadata.</p>
+<p>Use the <a
href="https://github.com/apache/tooling-asf-example/actions/workflows/announce-release-on-atr.yaml";><code>announce-release-on-atr.yaml</code></a>
workflow to announce the release and copy the files into the download area.</p>
diff --git a/docs/test-user-flows.md b/docs/test-user-flows.md
new file mode 100644
index 0000000..32e6614
--- /dev/null
+++ b/docs/test-user-flows.md
@@ -0,0 +1,71 @@
+# Test user flows
+
+To test the ATR, here are some example command line and GitHub user flows.
+
+## Command line
+
+To install the `atr` command, use the [the instructions in the client
`README.md`](https://github.com/apache/tooling-releases-client/tree/main?tab=readme-ov-file#quick-start),
or simply use `uv run atr` instead of `atr`.
+
+[Create a PAT](https://release-test.apache.org/tokens) using the UI, then
store the value in `atr` configuration.
+
+```
+atr set tokens.pat "$PAT_FROM_UI"
+```
+
+You can view the configuration file to check that the value is set. **This
will write secret values to stdout.**
+
+```
+atr config file
+```
+
+The following commands constitute roughly an entire flow, which will be
reflected in the UI. We are using `tooling-test-example` as the project name.
Don't forget to [create this or another
project](https://release-test.apache.org/project/add/tooling), or [use an
existing project](https://release-test.apache.org/committees) as applicable.
Use your ASF UID `@apache.org` instead of `example`.
+
+```
+atr release start tooling-test-example 0.1+demo
+
+atr upload tooling-test-example 0.1+demo example.txt ../example.txt
+
+atr check wait tooling-test-example 0.1+demo -i 25
+
+atr check status tooling-test-example 0.1+demo
+
+atr release info tooling-test-example 0.1+demo
+
+atr vote start tooling-test-example 0.1+demo 00002 -m [email protected]
+
+atr vote resolve tooling-test-example 0.1+demo passed
+
+atr distribution record tooling-test-example 0.1+demo NPM None react 18.2.0
False False
+
+atr release info tooling-test-example 0.1+demo
+
+atr announce tooling-test-example 0.1+demo 00003 -m [email protected] -s
Subject -b Body
+```
+
+When finished with an example flow, it is recommended that you delete the
version.
+
+```
+atr dev delete tooling-test-example 0.1+demo
+```
+
+If there is ever a problem with a JWT verification, try refreshing your JWT.
+
+```
+atr jwt refresh | wc
+```
+
+## GitHub actions
+
+We use [the
`tooling-asf-example`](https://github.com/apache/tooling-asf-example)
repository to check our GitHub actions.
+
+First, [start a new release in the ATR web
UI](https://release-test.apache.org/).
+
+You can then use the
[`build-and-rsync-to-atr.yaml`](https://github.com/apache/tooling-asf-example/actions/workflows/build-and-rsync-to-atr.yaml)
workflow to build Python wheel files an upload them to the ATR.
+
+Then, start a vote in the ATR web UI. This cannot be linked here because the
URL will depend on which project and version you use.
+
+Use the
[`resolve-vote-on-atr.yaml`](https://github.com/apache/tooling-asf-example/actions/workflows/resolve-vote-on-atr.yaml)
workflow to resolve the vote.
+
+Use the
[`record-distribution-on-atr.yaml`](https://github.com/apache/tooling-asf-example/actions/workflows/record-distribution-on-atr.yaml)
workflow to record an external distribution. The external distribution _must
exist_ on the distribution platform, because the ATR fetches real metadata.
+
+Use the
[`announce-release-on-atr.yaml`](https://github.com/apache/tooling-asf-example/actions/workflows/announce-release-on-atr.yaml)
workflow to announce the release and copy the files into the download area.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
