This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch sbp
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/sbp by this push:
new c78b269 Add documentation for users about checks
c78b269 is described below
commit c78b2691fd2547eca3376af08d0937c5520d9abc
Author: Sean B. Palmer <[email protected]>
AuthorDate: Fri Jan 30 20:03:18 2026 +0000
Add documentation for users about checks
---
atr/docs/check-ignores.md | 4 +-
atr/docs/checks.md | 115 +++++++++++++++++++++++++++++++++++++++++
atr/docs/index.md | 5 +-
atr/docs/license-checks.md | 6 +--
atr/docs/running-the-server.md | 2 +-
atr/docs/signing-artifacts.md | 2 +-
atr/docs/user-guide.md | 5 +-
7 files changed, 128 insertions(+), 11 deletions(-)
diff --git a/atr/docs/check-ignores.md b/atr/docs/check-ignores.md
index 36d8e27..9ca0eb6 100644
--- a/atr/docs/check-ignores.md
+++ b/atr/docs/check-ignores.md
@@ -1,8 +1,8 @@
-# 2.4. Check ignores
+# 2.5. Check ignores
**Up**: `2.` [User guide](user-guide)
-**Prev**: `2.3.` [License checks](license-checks)
+**Prev**: `2.4.` [License checks](license-checks)
**Next**: `3.1.` [Running the server](running-the-server)
diff --git a/atr/docs/checks.md b/atr/docs/checks.md
new file mode 100644
index 0000000..b469644
--- /dev/null
+++ b/atr/docs/checks.md
@@ -0,0 +1,115 @@
+# 2.3. Checks
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: `2.2.` [Signing artifacts](signing-artifacts)
+
+**Next**: `2.4.` [License checks](license-checks)
+
+**Sections**:
+
+* [Overview](#overview)
+* [How ATR selects checks](#how-atr-selects-checks)
+* [Understanding check results and
ignores](#understanding-check-results-and-ignores)
+* [Individual checks](#individual-checks)
+* [SBOM checks](#sbom-checks)
+* [Check caching and reruns](#check-caching-and-reruns)
+* [Project policy inputs](#project-policy-inputs)
+
+## Overview
+
+ATR runs automated checks on release artifacts so that you can validate
compliance and completeness before a vote. The checks focus on signatures,
hashes, archive layout, licensing, and software bill of materials (SBOM)
content. This document explains what ATR checks, when those checks run, and how
to interpret results.
+
+Checks are recorded against the release revision that you upload, and the
results remain visible to reviewers and voters. The checks run in the
background and appear in the checks view for the revision as they complete.
+
+## How ATR selects checks
+
+When you create or update a draft revision, ATR scans the files in the
revision directory and schedules checks based on file suffix and project
policy. A signature file with the `.asc` suffix triggers signature
verification. A checksum file with the `.sha256` or `.sha512` suffix triggers
hash verification. Archive files with the `.tar.gz`, `.tgz`, or `.zip` suffix
trigger archive integrity, archive structure, and license checks. Files with
the `.cdx.json` suffix trigger SBOM analysis. AT [...]
+
+Project policy tells ATR which artifacts are source artifacts and which are
binary artifacts, and it supplies exclusion patterns for license related
checks. Project policy also controls the license check mode for source
artifacts. You can choose lightweight checks, Apache RAT, or both for source
artifacts. Binary artifacts are not scanned by RAT, and always rely on the
lightweight checks.
+
+## Understanding check results and ignores
+
+Each check result has a status of success, warning, failure, or exception.
Success indicates that the check completed without issues. Warning indicates a
potential policy concern that needs review. Failure indicates a clear problem
such as a missing file, invalid signature, or invalid license. Exception
indicates that the check could not complete due to some unexpected internal ATR
error.
+
+If certain checks are producing false positives, or outcomes that you'd like
to ignore for reasons particular to your project, then you can ignore them
using special rules. Please try to minimise the use of such rules. If you would
like checks to change for all projects, you can file an ATR issue.
+
+Ignore rules match on the checker key and other fields. Only warning, failure,
and exception results can be ignored. Each check section below names the exact
checker key that ATR records for that check.
+
+You can [read more about check ignores](check-ignores).
+
+## Individual checks
+
+### Path and naming checks
+
+ATR validates the file layout of the revision against ASF release rules. For
each artifact it expects a matching signature file with the `.asc` suffix and
at least one checksum file with the `.sha256` or `.sha512` suffix. It verifies
that metadata files correspond to an existing artifact and warns when a
metadata suffix is recommended against by policy. It rejects `.md5` checksums
and `.sig` signature files and warns about `.sha1` and `.sha`. It rejects
dotfiles except for those under th [...]
+
+This check records separate checker keys for errors, warnings, and success.
Use `atr.tasks.checks.paths.check_errors` for failures and
`atr.tasks.checks.paths.check_warnings` for warnings when you configure ignores.
+
+(Success results use `atr.tasks.checks.paths.check_success` but are not
eligible for ignores.)
+
+### Hash verification
+
+For each `.sha256` or `.sha512` file, ATR computes the hash of the referenced
artifact and compares it with the expected value. It supports files that
contain just the hash as well as files that include a filename and hash on the
same line. If the suffix does not indicate `sha256` or `sha512`, the check
fails.
+
+The checker key is `atr.tasks.checks.hashing.check`.
+
+### Signature verification
+
+For each `.asc` signature file, ATR verifies the signature against the
matching artifact using the public keys stored for the release committee. The
signature is accepted only when it verifies and when the signing key is
associated with an ASF UID or matches the committee private email address
pattern of `private@`[_committee name_]`.apache.org`. If no suitable key is
found or the signature does not match the artifact, the check fails.
+
+The checker key is `atr.tasks.checks.signature.check`.
+
+### Archive integrity checks
+
+ATR checks that each `.tar.gz`, `.tgz`, or `.zip` archive can be read in full.
For tar based archives it reads all members using the tar reader. For zip
archives it lists members and verifies that the zip structure is valid.
Archives that are corrupted or contain too many members fail this check.
+
+The checker key for tar based archives is `atr.tasks.checks.targz.integrity`,
and the checker key for zip archives is `atr.tasks.checks.zipformat.integrity`.
+
+### Archive structure checks
+
+ATR expects each archive to contain exactly one root directory. The expected
root name is derived from the archive filename base, without extension. When
the archive filename base ends with the suffix `source` or `src`, ATR accepts a
root directory that either includes that suffix or omits it. When the archive
filename base has no such suffix, the root directory must match the base. If
the root does not match, ATR records a warning so that you can review project
conventions. Structure ch [...]
+
+ATR also recognizes `npm pack` archives. When the root directory is named
package, ATR looks for a file named `package.json` and validates that it
contains a name and version. If the file is present and valid, ATR treats this
layout as acceptable. If the package name and version do not match the archive
filename base, ATR records a warning.
+
+The checker key for tar based structure checks is
`atr.tasks.checks.targz.structure`. The checker key for zip structure checks is
`atr.tasks.checks.zipformat.structure`.
+
+### License files in archives
+
+ATR checks for `LICENSE` and `NOTICE` files at the top level of the root
directory each archive. It requires exactly one of each. The `LICENSE` content
must match the Apache License text with only whitespace differences. The
`NOTICE` file must be valid UTF-8 text and must include a product line, an ASF
copyright statement, and the standard ASF attribution line. For podling
projects ATR also requires a `DISCLAIMER` or `DISCLAIMER-WIP` file at the same
level. These lightweight license chec [...]
+
+The checker key is `atr.tasks.checks.license.files`.
+
+You can [read more about license checks](license-checks).
+
+### License headers in source files
+
+ATR performs a lightweight scan of source files inside each archive to verify
Apache License headers. It inspects the first four kilobytes of each file with
a recognized source file suffix and checks for the standard Apache License
header text. Files with generated file suffixes such as `.bundle.js`,
`.chunk.js`, `.css.map`, `.js.map`, `.min.css`, `.min.js`, and `.min.map` are
treated as generated and are skipped. Files that include generated markers such
as `Generated By JJTree` or `Gen [...]
+
+The checker key is `atr.tasks.checks.license.headers`.
+
+You can [read more about license checks](license-checks).
+
+### Apache RAT license scan
+
+ATR can run Apache RAT on source archives unless your project policy selects
lightweight mode only. RAT runs in a temporary extraction directory, uses
standard exclusions for common SCM and IDE files, and always excludes known
generated file patterns. If the archive includes a RAT excludes file with the
standard name `.rat-excludes`, ATR uses it as the exclusion file and sets the
scan root to the directory that contains it. ATR records an error if more than
one such file is present or if [...]
+
+The checker key is `atr.tasks.checks.rat.check`.
+
+You can [read more about license checks](license-checks).
+
+## SBOM checks
+
+ATR recognizes CycloneDX SBOM files with the `.cdx.json` suffix. When you
upload such a file, ATR runs a special scoring tool check that evaluates NTIA
2021 conformance, CycloneDX validation results, license signals, and
vulnerability data derived from the SBOM. If a previous release exists, ATR
compares current and prior license and vulnerability information and records
that context with the result. ATR also provides additional SBOM tasks that you
can run from the interface: you can ask [...]
+
+SBOM tasks record task results rather than check results, so there is no
checker key to use in ignore rules for SBOM tasks. The results are presented
separately from regular checks, on their own page.
+
+## Check caching and reruns
+
+To save time, ATR will sometimes reuse results from a prior revision when a
file has not changed. The system computes a content hash and copies earlier
results so that the same check does not run again.
+
+_For debugging only_, if you need a fresh run, place a file named
`.atr-no-cache` in the revision root. When that file is present, ATR does not
reuse cached results for that revision. We may remove this functionality.
+
+## Project policy inputs
+
+Several checks depend on project policy. You can define which paths are
considered source artifacts and which are considered binary artifacts, and you
can define exclusion patterns for the RAT scan and for the lightweight license
header check. These settings affect which checks run and which files are
skipped. If no policy pattern matches a file, ATR treats it as a source
artifact for the purpose of the lightweight and RAT license checks.
diff --git a/atr/docs/index.md b/atr/docs/index.md
index 85556b9..b8d49fc 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -10,8 +10,9 @@ NOTE: This documentation is a work in progress.
* `2.` [User guide](user-guide)
* `2.1.` [Components](components)
* `2.2.` [Signing artifacts](signing-artifacts)
- * `2.3.` [License checks](license-checks)
- * `2.4.` [Check ignores](check-ignores)
+ * `2.3.` [Checks](checks)
+ * `2.4.` [License checks](license-checks)
+ * `2.5.` [Check ignores](check-ignores)
* `3.` [Developer guide](developer-guide)
* `3.1.` [Running the server](running-the-server)
* `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/license-checks.md b/atr/docs/license-checks.md
index 77df4bf..276388d 100644
--- a/atr/docs/license-checks.md
+++ b/atr/docs/license-checks.md
@@ -1,10 +1,10 @@
-# 2.3. License checks
+# 2.4. License checks
**Up**: `2.` [User guide](user-guide)
-**Prev**: `2.2.` [Signing artifacts](signing-artifacts)
+**Prev**: `2.3.` [Checks](checks)
-**Next**: `2.4.` [Check ignores](check-ignores)
+**Next**: `2.5.` [Check ignores](check-ignores)
**Sections**:
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index 73d15aa..9b50270 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: `2.4.` [Check ignores](check-ignores)
+**Prev**: `2.5.` [Check ignores](check-ignores)
**Next**: `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/signing-artifacts.md b/atr/docs/signing-artifacts.md
index d7be3a2..52a9d54 100644
--- a/atr/docs/signing-artifacts.md
+++ b/atr/docs/signing-artifacts.md
@@ -4,7 +4,7 @@
**Prev**: `2.1.` [Components](components)
-**Next**: `2.3.` [License checks](license-checks)
+**Next**: `2.3.` [Checks](checks)
**Sections**:
diff --git a/atr/docs/user-guide.md b/atr/docs/user-guide.md
index 00f3a38..b8d6157 100644
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -10,8 +10,9 @@
* `2.1.` [Components](components)
* `2.2.` [Signing artifacts](signing-artifacts)
-* `2.3.` [License checks](license-checks)
-* `2.4.` [Check ignores](check-ignores)
+* `2.3.` [Checks](checks)
+* `2.4.` [License checks](license-checks)
+* `2.5.` [Check ignores](check-ignores)
**Sections**:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
