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-releases.git
The following commit(s) were added to refs/heads/main by this push:
new f6ed9bd Add a note about trivial changes to test PRs and remove HTML
note files
f6ed9bd is described below
commit f6ed9bd48093a6db3559c924ada1a360282f2c6b
Author: Sean B. Palmer <[email protected]>
AuthorDate: Tue Oct 21 14:39:41 2025 +0100
Add a note about trivial changes to test PRs and remove HTML note files
---
Makefile | 6 +-
notes/api-security.html | 22 ----
notes/development.html | 15 ---
notes/outcome-design-patterns.html | 26 ----
notes/plan.html | 239 -------------------------------------
notes/test-user-flows.html | 45 -------
notes/trivial-changes.md | 9 ++
7 files changed, 12 insertions(+), 350 deletions(-)
diff --git a/Makefile b/Makefile
index 1462618..9203f4f 100644
--- a/Makefile
+++ b/Makefile
@@ -49,13 +49,13 @@ commit:
docs:
uv run python3 scripts/docs_check.py
- rm -f atr/docs/*.html notes/*.html
+ rm -f atr/docs/*.html
uv run python3 scripts/docs_build.py
- for fn in atr/docs/*.md notes/*.md; \
+ for fn in atr/docs/*.md; \
do \
cmark "$$fn" > "$${fn%.md}.html"; \
done
- uv run python3 scripts/docs_post_process.py atr/docs/*.html notes/*.html
+ uv run python3 scripts/docs_post_process.py atr/docs/*.html
uv run python3 scripts/docs_check.py
generate-version:
diff --git a/notes/api-security.html b/notes/api-security.html
deleted file mode 100644
index c545921..0000000
--- a/notes/api-security.html
+++ /dev/null
@@ -1,22 +0,0 @@
-<h1 id="atr-api-security-model">ATR API security model</h1>
-<p>All ATR routes, on both the website and the API, require HTTPS using TLS
1.2 or newer for their transport.</p>
-<p>There are two access levels to the ATR API: public and committer. Public
API endpoints are accessible to everybody. Committer endpoints have the
following accessibility criteria instead.</p>
-<h2 id="pats">PATs</h2>
-<p>Committers must obtain a <a
href="https://en.wikipedia.org/wiki/Personal_access_token";>Personal Access
Token</a> (PAT) from the ATR website at the route <code>/tokens</code>. Only
committers, signed in through <a href="https://oauth.apache.org/api.html";>ASF
OAuth</a> to ATR, can obtain PATs. Each PAT expires in 180 days, and can be
revoked at any time by the user at the same route. ATR does not store PATs,
only the hashes of PATs.</p>
-<h2 id="jwts">JWTs</h2>
-<p>To make a request to a committer protected endpoint on the API, committers
must first obtain a <a
href="https://en.wikipedia.org/wiki/JSON_Web_Token";>JWT</a>. They can do this
in one of two ways:</p>
-<ol>
-<li>For debugging, obtaining a JWT from the <code>/tokens</code> page.</li>
-<li>For script use, obtaining a JWT by POSTing their PAT in a JSON payload to
the API endpoint <code>/api/jwt</code>. This is a public route, and requires a
payload such as <code>{"asfuid": "${ASF_UID}", "pat": "${PAT_TOKEN}"}</code>.
The response will be <code>{"asfuid": "${ASF_UID}", "jwt":
"${JWT_TOKEN}"}</code>.</li>
-</ol>
-<p>Every JWT issued by the ATR expires in 90 minutes, uses the HS256
(HMAC-SHA256) algorithm, and makes <code>sub</code> (ASF UID), <code>iat</code>
(issue time), <code>exp</code> (expires at), and <code>jti</code> (token
payload) claims. JWTs are stateless, so there is no analogue stored by the ATR,
except for the secret symmetric key of the server which is initialised on
startup. If the ATR server is restarted, all JWTs are expired immediately.</p>
-<p>The JWT can be used to access protected endpoints by using it in the
<code>Authorization</code> header as a bearer token, i.e. <code>Authorization:
Bearer ${JWT_TOKEN}</code>. PATs and JWTs must never appear in URLs. They must
be protected by the user at all times. Accidental sharing of a PAT or a JWT
must be reported to ASF security.</p>
-<p>Note that PATs cannot be used to access protected endpoints. They can only
be used to issue a JWT, which is then used to access protected endpoints.</p>
-<p>Endpoints which mutate state, require significant computation, or have
large or sensitive payloads use POST. All other endpoints use GET.</p>
-<h2 id="limitations">Limitations</h2>
-<p>We do not currently support scopes in either PATs or JWTs, but are
considering this.</p>
-<p>Admins are able to revoke any PAT, and users are able to revoke any of
their own PATs, but neither admins nor users are able to revoke JWTs on an
individual basis. Restarting the server resets the server secret symmetric key,
which has the side effect of expiring all JWTs, and can be used in an
emergency.</p>
-<p>We do not have refresh tokens, and do not plan to implement refresh tokens.
PATs must be used to issue a new JWT through the API.</p>
-<p>We do not presently have logging or auditing of the logging for the API.
Once we implement logging, we must ensure that tokens and other sensitive data
are not stored.</p>
-<p>We do not use all available JWT fields, such as <code>iss</code>
(issuer).</p>
-<p>We do not rate limit PAT or JWT issuance.</p>
diff --git a/notes/development.html b/notes/development.html
deleted file mode 100644
index 1f6fb53..0000000
--- a/notes/development.html
+++ /dev/null
@@ -1,15 +0,0 @@
-<h1 id="development">Development</h1>
-<p>You will need to have a working <a
href="https://www.python.org/downloads/release/python-3132/";>Python 3.13</a>
installation, <a href="https://docs.astral.sh/uv/";>uv</a>, <a
href="https://github.com/FiloSottile/mkcert";>mkcert</a>, and a POSIX compliant
<code>make</code>. To optionally build the HTML documentation files you will
also need <a href="https://github.com/commonmark/cmark";>cmark</a>.</p>
-<p>Ensure that you have the pre-commit hook installed:</p>
-<pre><code class="language-shell">make sync PYTHON="$(which python3)"
-poetry run pre-commit install
-</code></pre>
-<p>To run the project, use the following commands, which will add a local CA
root to your OS and browser certificate qstore if using Firefox:</p>
-<pre><code class="language-shell">uv sync --all-groups
-make certs-local
-make serve
-</code></pre>
-<p>And add the following line to your <code>/etc/hosts</code>:</p>
-<pre><code>127.0.0.1 localhost.apache.org
-</code></pre>
-<p>The website will be available at <a
href="https://localhost.apache.org:8080/";>https://localhost.apache.org:8080/</a>
using a self-signed certificate.</p>
diff --git a/notes/outcome-design-patterns.html
b/notes/outcome-design-patterns.html
deleted file mode 100644
index e52a676..0000000
--- a/notes/outcome-design-patterns.html
+++ /dev/null
@@ -1,26 +0,0 @@
-<h1 id="outcome-design-patterns">Outcome design patterns</h1>
-<p>One common pattern when designing outcome types is about how to handle an
<strong>exception after a success</strong>, and how to handle a <strong>warning
during success</strong>:</p>
-<ul>
-<li>An <strong>exception after a success</strong> is when an object is
processed in multiple stages, and the first few stages succeed but then
subsequently there is an exception.</li>
-<li>A <strong>warning during success</strong> is when an object is processed
in multiple stages, an exception is raised, but we determine that we can
proceed to subsequent stages as long as we keep a note of the exception.</li>
-</ul>
-<p>Both of these workflows appear incompatible with outcomes. In outcomes, we
can record <em>either</em> a successful result, <em>or</em> an exception. But
in exception after success we want to record the successes up to the exception;
and in a warning during a success we want to record the exception even though
we return a success result.</p>
-<p>The solution is similar in both cases: create a wrapper of the <em>primary
type</em> which can hold an instance of the <em>secondary type</em>.</p>
-<p>In <em>exception after a success</em> the primary type is an exception, and
the secondary type is the result which was obtained up to that exception. The
type will look like this:</p>
-<pre><code class="language-python">class AfterSuccessError(Exception):
- def __init__(self, result_before_error: Result):
- self.result_before_error = result_before_error
-</code></pre>
-<p>In <em>warning during success</em>, the primary type is the result, and the
secondary type is the exception raised during successful processing which we
consider a warning. This is the inverse of the above, and the types are
therefore inverted too.</p>
-<pre><code class="language-python">@dataclasses.dataclass
-class Result:
- value: Value
- warning: Exception | None
-</code></pre>
-<p>This could just as easily be a Pydantic class or whatever is appropriate in
the situation, as long as it can hold the warning. If the warning is generated
during an additional or side task, we can use <code>Outcome[SideValue]</code>
instead. We do this, for example, in the type representing a linked
committee:</p>
-<pre><code class="language-python">@dataclasses.dataclass
-class LinkedCommittee:
- name: str
- autogenerated_keys_file: Outcome[str]
-</code></pre>
-<p>In this case, if the autogenerated keys file call succeeded without an
error, the <code>Outcome</code> will be an <code>OutcomeResult[str]</code>
where the <code>str</code> represents the full path to the autogenerated
file.</p>
diff --git a/notes/plan.html b/notes/plan.html
deleted file mode 100644
index 2f58ce7..0000000
--- a/notes/plan.html
+++ /dev/null
@@ -1,239 +0,0 @@
-<h1 id="implementation-plan">Implementation plan</h1>
-<p>This is a rough plan of immediate tasks. The priority of these tasks may
change, and we may add or drop tasks as appropriate using a reactive
development style.</p>
-<h2 id="ux-improvements">UX improvements</h2>
-<ol>
-<li>
-<p>Improve RC workflow</p>
-<ul>
-<li>[DONE] Allow upload of checksum file alongside artifacts and
signatures</li>
-<li>[DONE] Add a form field to choose the RC artifact type</li>
-<li>[DONE] Allow extra types of artifact, such as reproducible binary and
convenience binary</li>
-<li>[DONE] Differentiate between podling PPMCs and top level PMCs</li>
-<li>[DONE] Allow package deletion</li>
-<li>[DONE] Allow RCs to be deleted</li>
-<li>[DONE] Move signature verification to a task runner</li>
-<li>[DONE] Add a method to allow the bulk addition of RC artifacts</li>
-<li>Improve the existing method to allow the bulk addition of RC artifacts</li>
-<li>Add further methods to allow the bulk addition of RC artifacts</li>
-</ul>
-</li>
-<li>
-<p>Enhance RC display</p>
-<ul>
-<li>[DONE] Augment raw file hashes with the original filenames in the UI</li>
-<li>[DONE] Add file size and upload timestamp</li>
-<li>[DONE] Improve the layout of file listings</li>
-<li>[DONE] Show KB, MB, or GB units for file sizes</li>
-<li>[DONE] Add a standard artifact naming pattern based on the committee and
project</li>
-<li>[DONE] Potentially add the option to upload package artifacts without
signatures</li>
-<li>[DONE] Show validation status indicators</li>
-<li>[DONE] Add developer RC download buttons with clear verification
instructions</li>
-<li>Make developer RC download buttons public for external developers</li>
-<li>Improve validation status indicators</li>
-</ul>
-</li>
-<li>
-<p>Improve key management interface</p>
-<ul>
-<li>[DONE] Display which PMCs are using each key</li>
-<li>[DONE] Add key expiration warnings</li>
-<li>[DONE] Fix reported problem with adding keys</li>
-<li>[DONE] Add debugging output error messages for when key addition fails</li>
-<li>Allow adding keys from a KEYS file</li>
-<li>Allow +1 binding voters to have their signatures added to the release</li>
-</ul>
-</li>
-<li>
-<p>Release status dashboard</p>
-<ul>
-<li>Add progress indicators for release phases</li>
-<li>Show current blockers and required actions</li>
-<li>Add quick actions for release managers</li>
-</ul>
-</li>
-<li>
-<p>General website improvements</p>
-<ul>
-<li>Add orienting style or features to improve navigability</li>
-</ul>
-</li>
-</ol>
-<p>Advanced tasks, possibly deferred</p>
-<ul>
-<li>Implement a key revocation workflow</li>
-<li>Check RC file naming conventions</li>
-<li>Add ability to sign artifact hashes on the platform using JS</li>
-</ul>
-<h2 id="task-scheduler">Task scheduler</h2>
-<p>We aim to work on the task scheduler in parallel with the UX improvements
above. Artifact validation and the release status dashboard are dependent on
tasks, which are managed by the task scheduler.</p>
-<ol>
-<li>
-<p>Task runner workers</p>
-<ul>
-<li>[DONE] Implement worker process with RLIMIT controls for CPU and RAM</li>
-<li>[DONE] Implement safe handling for compressed asset expansion</li>
-<li>[DONE] Test external tool use</li>
-<li>Track the duration of tasks in milliseconds</li>
-<li>Add disk usage tracking through API and psutil polling</li>
-<li>Add rollback or reporting for failed tasks</li>
-<li>Ensure idempotent operations where possible</li>
-<li>Consider distinguishing between issue and error states</li>
-<li>Use consistent task status values (pending, running, passed, issue,
error?)</li>
-<li>Add a warning task result status</li>
-<li>Allow dependencies between tasks to reduce duplication of effort</li>
-<li>Add UI to restart all waiting workers</li>
-</ul>
-</li>
-<li>
-<p>Orchestrating manager and resource management</p>
-<ul>
-<li>[DONE] Implement process-based task isolation</li>
-<li>[DONE] Create task table in sqlite database</li>
-<li>[DONE] Add task queue management</li>
-<li>Track and limit disk usage per task in the manager</li>
-</ul>
-</li>
-<li>
-<p>Improve the task UI</p>
-<ul>
-<li>[DONE] Allow restarting all tasks when inactive</li>
-<li>Test that tasks are deleted when a package is deleted</li>
-</ul>
-</li>
-</ol>
-<p>Advanced tasks, possibly deferred</p>
-<ul>
-<li>Check fair scheduling across cores</li>
-<li>Add task monitoring and reporting</li>
-</ul>
-<h2 id="site-improvements">Site improvements</h2>
-<ol>
-<li>
-<p>Fix bugs and improve workflow</p>
-<ul>
-<li>[DONE] Add ATR commit or version number to the UI</li>
-<li>[DONE] Fix and improve the package checks summary count</li>
-<li>[DONE] Improve the proprietary platform patch in ASFQuart</li>
-<li>[DONE] Ensure that all errors are caught and logged or displayed</li>
-<li>Add further tests</li>
-<li>Decide whether to use Alembic and, if not, remove
<code>alembic.cfg</code></li>
-</ul>
-</li>
-<li>
-<p>Ensure that performance is optimal</p>
-<ul>
-<li>[DONE] Add page load timing metrics to a log</li>
-<li>[DONE] Add a basic metrics dashboard</li>
-</ul>
-</li>
-<li>
-<p>Increase the linting, type checking, and other QA</p>
-<ul>
-<li>[DONE] Potentially add blockbuster</li>
-<li>Create website UX integration tests using a browser driver</li>
-</ul>
-</li>
-</ol>
-<p>Advanced tasks, possibly deferred</p>
-<ul>
-<li>Patch the synchronous behaviour in Jinja and submit upstream</li>
-</ul>
-<h2 id="basic-rc-validation">Basic RC validation</h2>
-<p>These tasks are dependent on the task scheduler above.</p>
-<ol>
-<li>
-<p>Basic artifact validation</p>
-<ul>
-<li>[DONE] Implement basic archive verification</li>
-<li>[DONE] Implement basic signature verification</li>
-</ul>
-</li>
-<li>
-<p>License compliance</p>
-<ul>
-<li>[DONE] Verify LICENSE and NOTICE files exist and are placed correctly</li>
-<li>[DONE] Check for Apache License headers in source files</li>
-<li>[DONE] Basic RAT integration for license header validation</li>
-</ul>
-</li>
-<li>
-<p>SBOM integration</p>
-<ul>
-<li>[DONE] Generate a basic SBOM for release artifacts</li>
-<li>Store SBOMs with release metadata</li>
-<li>Add SBOM management options to UI</li>
-<li>Ensure that release managers are made aware of SBOM quality and contents
in the UI</li>
-<li>Add ability to upload existing SBOMs</li>
-<li>Add ability to validate uploaded SBOMs</li>
-<li><a
href="https://github.com/apache/tooling-trusted-releases/issues/8";>Export data
through the Transparency Exchange API</a></li>
-</ul>
-</li>
-</ol>
-<h2 id="advanced-rc-validation">Advanced RC validation</h2>
-<ol>
-<li>
-<p>Reproducible build verification</p>
-<ul>
-<li>[DONE] Accept upload of binary packages</li>
-<li>Compare built artifacts with any existing provided binary artifacts</li>
-<li>Give a detailed report of differences between user provided builds</li>
-</ul>
-</li>
-<li>
-<p>Dependency analysis</p>
-<ul>
-<li>Parse and validate dependency licenses</li>
-<li>Check for prohibited licenses</li>
-<li>Generate dependency reports</li>
-<li>Flag dependency vulnerabilities</li>
-</ul>
-</li>
-<li>
-<p>Distribution channel integration</p>
-<ul>
-<li>Add PyPI distribution support</li>
-<li>Implement Maven Central publishing</li>
-<li>Add Docker Hub integration</li>
-<li>Support test distribution channels</li>
-</ul>
-</li>
-</ol>
-<h2 id="process-automation">Process automation</h2>
-<p>These are long term implementation requirements.</p>
-<ol>
-<li>
-<p>Vote management</p>
-<ul>
-<li>Automate vote thread creation</li>
-<li>Track votes and calculate results</li>
-<li>Generate vote summaries</li>
-<li>Handle binding vs non-binding votes</li>
-<li>Display vote status and timeline</li>
-</ul>
-</li>
-<li>
-<p>Release announcement</p>
-<ul>
-<li>Template-based announcement generation with all required metadata</li>
-<li>Support customisation by PMCs</li>
-<li>Automate mailing list distribution</li>
-</ul>
-</li>
-<li>
-<p>GitHub integration</p>
-<ul>
-<li>Support GHA-based release uploads</li>
-<li>Add release tagging integration</li>
-<li>Support automated PR creation</li>
-<li>Implement security checks for GHA workflows</li>
-</ul>
-</li>
-</ol>
-<h2 id="success-metrics">Success metrics</h2>
-<ul>
-<li>Increased number of PMCs using the platform</li>
-<li>Reduction in release process duration</li>
-<li>Decreased number of failed release votes</li>
-<li>Improved compliance with ASF release policies</li>
-<li>Reduced manual intervention in release process</li>
-</ul>
diff --git a/notes/test-user-flows.html b/notes/test-user-flows.html
deleted file mode 100644
index 660e59e..0000000
--- a/notes/test-user-flows.html
+++ /dev/null
@@ -1,45 +0,0 @@
-<h1 id="test-user-flows">Test user flows</h1>
-<p>To test the ATR, here are some example command line and GitHub user
flows.</p>
-<h2 id="command-line">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";>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 id="github-actions">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 and 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/notes/trivial-changes.md b/notes/trivial-changes.md
new file mode 100644
index 0000000..532efcd
--- /dev/null
+++ b/notes/trivial-changes.md
@@ -0,0 +1,9 @@
+# How to make a trivial change in ATR
+
+Sometimes it is necessary to make a trivial change in ATR to e.g. test pull
request workflows or lints.
+
+The recommended approach for doing so is to update the following timestamp:
+
+1761155762
+
+By changing the timestamp in this file, it makes it clear that the intent of
your change was to make a trivial change. Please also describe the wider intent
of the change in your comment message subject.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
