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 52f70c8 docs: document generated source file detection and exclusions
(Fixes #477)
52f70c8 is described below
commit 52f70c8bcf7544245a37825fc7aa4429ddf5ae46
Author: Sanjana <[email protected]>
AuthorDate: Fri Jan 23 15:45:39 2026 +0530
docs: document generated source file detection and exclusions (Fixes #477)
---
atr/docs/index.md | 1 +
atr/docs/license-checks.md | 86 ++++++++++++++++++++++++++++++++++++++++++
atr/docs/running-the-server.md | 2 +-
atr/docs/signing-artifacts.md | 2 +-
atr/docs/user-guide.md | 1 +
5 files changed, 90 insertions(+), 2 deletions(-)
diff --git a/atr/docs/index.md b/atr/docs/index.md
index 9a0a57f..72262b9 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -10,6 +10,7 @@ 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)
* `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
new file mode 100644
index 0000000..2275c83
--- /dev/null
+++ b/atr/docs/license-checks.md
@@ -0,0 +1,86 @@
+# 2.3. License checks
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: `2.2.` [Signing artifacts](signing-artifacts)
+
+**Next**: `3.1.` [Running the server](running-the-server)
+
+**Sections**:
+
+* [Check selection](#check-selection)
+* [Automatically excluded patterns](#automatically-excluded-patterns)
+* [Apache RAT check](#apache-rat-check)
+* [Lightweight license check](#lightweight-license-check)
+* [Project policy exclusions](#project-policy-exclusions)
+
+## Check selection
+
+When you configure a release, you can choose which checks run on **source
artifacts**:
+
+* **Lightweight only**: Run just the lightweight check.
+* **RAT only**: Run just the Apache RAT check.
+* **Both**: Run both (the default).
+
+**Binary artifacts** are always checked with the lightweight check. You can't
turn this off.
+
+## Automatically excluded patterns
+
+These file patterns are automatically treated as "generated" and are ignored
by **both** the RAT check and the lightweight check:
+
+* `**/*.bundle.js`
+* `**/*.chunk.js`
+* `**/*.css.map`
+* `**/*.js.map`
+* `**/*.min.css`
+* `**/*.min.js`
+* `**/*.min.map`
+
+## Apache RAT check
+
+The Apache RAT (Release Audit Tool) scans every file in the archive.
+
+### Standard exclusions
+
+If you don't provide a custom exclusion file, RAT uses a default config that
excludes:
+
+* Standard SCM directories (like `.git`, `.svn`)
+* IDE configuration files
+
+### Custom exclusions
+
+You can define your own exclusions by adding a `.rat-excludes` file to the
archive.
+
+> [!IMPORTANT]
+> If a `.rat-excludes` file exists, the **standard exclusions are ignored**.
+
+**Scan root behavior**:
+You can only have one `.rat-excludes` file. The folder it's in becomes the
**scan root**.
+
+* Everything you want checked must be inside this scan root (or subfolders).
+* Files outside this root might cause errors or get ignored in weird ways.
It's best to just put `.rat-excludes` at the very top of your archive.
+
+## Lightweight license check
+
+This check looks at source files to see if they have valid license headers.
+
+### Content-based exclusions
+
+Files are skipped (considered generated) if the first 4KB of the file contains
one of these markers:
+
+* `Generated By:JJTree`
+* `Generated By:JavaCC`
+
+### Included file types
+
+Unlike RAT, the lightweight check uses an allowlist of file extensions (e.g.,
`.js`, `.py`, `.java`, etc.). If a file extension isn't in the list, it gets
ignored by default.
+
+## Project policy exclusions
+
+On top of file-based exclusions, you can configure exclusions right in the ATR
web interface.
+When editing a project, look for the **License Check Exclusions** fields:
+
+* **RAT Exclusions**: newline-separated patterns to exclude from RAT checks.
+* **Lightweight Exclusions**: newline-separated patterns to exclude from
lightweight checks.
+
+These settings follow the project, not the artifact.
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index 2f37dc8..211f4d3 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.2.` [Signing artifacts](signing-artifacts)
+**Prev**: `2.3.` [License checks](license-checks)
**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 7f657cb..d7be3a2 100644
--- a/atr/docs/signing-artifacts.md
+++ b/atr/docs/signing-artifacts.md
@@ -4,7 +4,7 @@
**Prev**: `2.1.` [Components](components)
-**Next**: `3.1.` [Running the server](running-the-server)
+**Next**: `2.3.` [License checks](license-checks)
**Sections**:
diff --git a/atr/docs/user-guide.md b/atr/docs/user-guide.md
index 8004289..5670125 100644
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -10,6 +10,7 @@
* `2.1.` [Components](components)
* `2.2.` [Signing artifacts](signing-artifacts)
+* `2.3.` [License checks](license-checks)
**Sections**:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
