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 9ed7ff0 Improve the instructions for new external contributors
9ed7ff0 is described below
commit 9ed7ff0a1c5c188634d050676404706e99d1fbc1
Author: Sean B. Palmer <[email protected]>
AuthorDate: Mon Jan 12 14:23:28 2026 +0000
Improve the instructions for new external contributors
---
atr/docs/how-to-contribute.md | 12 +++++++-----
atr/docs/running-and-creating-tests.md | 13 +++++++++----
notes/for-prospective-contributors.md | 23 +++++++++++++++++++++++
3 files changed, 39 insertions(+), 9 deletions(-)
diff --git a/atr/docs/how-to-contribute.md b/atr/docs/how-to-contribute.md
index 9abfd11..3c41c7a 100644
--- a/atr/docs/how-to-contribute.md
+++ b/atr/docs/how-to-contribute.md
@@ -40,15 +40,17 @@ Once you have identified something to work on, the process
of contributing is as
3. **Create a branch.** [Create a new
branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
for your work. Use a descriptive name that indicates what you are working on,
such as `fix-typo-in-docs` or `improve-error-messages`.
-4. **Make your changes.** Implement your fix or feature, following our [code
conventions](code-conventions). If you are changing code, ensure that your
changes do not break existing functionality. Whenever you change code, and
especially if you are adding a new feature, consider [adding a
test](running-and-creating-tests).
+4. **Ensure that you enable pre-commit checks.** Download
[pre-commit](https://pre-commit.com/) and run `pre-commit install` in the ATR
repository where you are going to make your changes.
-5. **Commit your changes.** Write clear, concise commit messages following
[our commit message style](#commit-message-style). Each commit should represent
a logical unit of work, but we are not particularly strict about this.
+5. **Make your changes.** Implement your fix or feature, following our [code
conventions](code-conventions). If you are changing code, ensure that your
changes do not break existing functionality. Whenever you change code, and
especially if you are adding a new feature, consider [adding a
test](running-and-creating-tests).
-6. **Push your branch.** Push your branch to your fork on GitHub.
+6. **Commit your changes.** Write clear, concise commit messages following
[our commit message style](#commit-message-style). Each commit should represent
a logical unit of work, but we are not particularly strict about this.
-7. **Create a pull request (PR).** The PR should be from your branch to the
`main` branch of the ATR repository. In the PR description, explain what your
changes do and why they are needed. If your PR addresses an existing issue,
reference that issue by number. Use the rebase strategy, not merge, to keep
your PR up to date as you work on it.
+7. **Push your branch.** Push your branch to your fork on GitHub.
-8. **Participate in code review.** A member of the Tooling team will review
your PR and may request changes. _We strongly recommend enabling the option to
allow maintainers to edit your PR when you create it._ Even if you allow us to
make changes, we may still ask you to make the changes yourself. Also, because
of the stringent security and usability requirements for ATR, we accept only
[high quality contributions](#special-considerations-for-atr).
+8. **Create a pull request (PR).** The PR should be from your branch to the
`main` branch of the ATR repository. In the PR description, explain what your
changes do and why they are needed. If your PR addresses an existing issue,
reference that issue by number. Use the rebase strategy, not merge, to keep
your PR up to date as you work on it. Mark your PR as a draft until it is ready
for review.
+
+9. **Participate in code review.** A member of the Tooling team will review
your PR and may request changes. _We strongly recommend enabling the option to
allow maintainers to edit your PR when you create it._ Even if you allow us to
make changes, we may still ask you to make the changes yourself. Also, because
of the stringent security and usability requirements for ATR, we accept only
[high quality contributions](#special-considerations-for-atr).
You can also [email
patches](https://lists.apache.org/[email protected]) if you
prefer not to use GitHub. Please use standard Git patch formatting, as if you
were e.g. contributing to the Linux Kernel.
diff --git a/atr/docs/running-and-creating-tests.md
b/atr/docs/running-and-creating-tests.md
index 8d123f8..8d42c67 100644
--- a/atr/docs/running-and-creating-tests.md
+++ b/atr/docs/running-and-creating-tests.md
@@ -8,10 +8,11 @@
**Sections**:
-* [Running tests](#running-tests)
-* [Creating tests](#creating-tests)
+* [Running Playwright tests](#running-playwright-tests)
+* [Creating Playwright tests](#creating-playwright-tests)
+* [Running end-to-end tests](#running-end-to-end-tests)
-## Running tests
+## Running Playwright tests
We currently only have end-to-end browser tests, but we plan to expand these
as part of [Issue
#209](https://github.com/apache/tooling-trusted-releases/issues/209).
Meanwhile, these browser tests serve as a simple consistency check when
developing ATR.
@@ -48,7 +49,7 @@ In other words, we build
[`tests/Dockerfile.playwright`](/ref/tests/Dockerfile.p
The tests should, as of 14 Oct 2025, take about 40 to 50 seconds to run in
Docker Compose, and 20 to 25 seconds to run on the host. The last line of the
test output should be `Tests finished successfully`, and if the tests do not
complete successfully there should be an obvious Python backtrace.
-## Creating tests
+## Creating Playwright tests
You can add tests to `playwright/test.py`. If you're feeling particularly
adventurous, you can add separate unit tests etc., but it's okay to add tests
only to the Playwright test script until [Issue
#209](https://github.com/apache/tooling-trusted-releases/issues/209) is
resolved.
@@ -63,3 +64,7 @@ The `test.py` script calls
[`run_tests`](/ref/playwright/test.py:run_tests) from
We want to make it more clear which Playwright tests depend on which, and have
more isolated tests. Reusing context, however, helps to speed up the tests.
The actual test cases themselves tend to use helpers such as
[`go_to_path`](/ref/playwright/test.py:go_to_path) and
[`wait_for_path`](/ref/playwright/test.py:wait_for_path), and then call
[`logging.info`](https://docs.python.org/3/library/logging.html#logging.info)
to print information to the console. Try to keep logging messages terse and
informative.
+
+## Running end-to-end tests
+
+To run ATR end-to-end (e2e) tests, you must first have an OCI container
runtime with Compose functionality, such as Docker or Podman, installed. You
will also need a POSIX shell. You can then run `tests/run-e2e.sh` to run the
entire e2e test suite.
diff --git a/notes/for-prospective-contributors.md
b/notes/for-prospective-contributors.md
new file mode 100644
index 0000000..625ccc6
--- /dev/null
+++ b/notes/for-prospective-contributors.md
@@ -0,0 +1,23 @@
+**Instructions for prospective contributors:** <!-- markdownlint-disable-line
MD041 -->
+
+Thank you for your offer to help with ATR! We require new contributors who are
not existing ASF committers to send a message of introduction to our
development mailing list.
+
+Please follow these instructions carefully:
+
+1. Send an empty message to
[[email protected]](mailto:[email protected])
+
+2. Reply to the automated response to subscribe
+
+3. Send a message to [[email protected]](mailto:[email protected])
introducing yourself. Your message must also contain the last ten lines of
output from ATR pre-commit checks, and the last ten lines of output from the
e2e tests
+
+_These instructions do not apply to trivial changes such as bug fixes or the
correction of typographical errors. They do, however, apply to any substantial
documentation changes._
+
+We **only accept PRs that have been linted and tested**. You will need to run
and test ATR in order to contribute. Please see the following guides:
+
+* [How to run the ATR
server](https://release-test.apache.org/docs/running-the-server)
+* [How to run ATR pre-commit
checks](https://release-test.apache.org/docs/how-to-contribute#pull-request-workflow)
+* [How to run and create ATR
tests](https://release-test.apache.org/docs/running-and-creating-tests#running-end-to-end-tests)
+
+You must mark your PR as a draft until it is ready for review. You must use
the rebase strategy to keep your PR up to date with the `main` branch. Please
follow everything in the [contribution
guide](https://release-test.apache.org/docs/how-to-contribute) and the [code
conventions](https://release-test.apache.org/docs/code-conventions).
+
+Thank you again for the offer of contribution. We hope that these requirements
and the volume of reading will not deter you from contributing. ATR is used to
bolster supply chain security, so we put these procedures in place to help to
ensure a high quality of contributions. If you have any problems following
these instructions, please [open a new GitHub
issue](https://github.com/apache/tooling-trusted-releases/issues/new?template=BLANK_ISSUE).
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
