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 65d574c Fix some documentation pages and document the convention
65d574c is described below
commit 65d574c05a871119c40d7ebec6e546228041f3d0
Author: Sean B. Palmer <[email protected]>
AuthorDate: Fri Jan 30 15:46:49 2026 +0000
Fix some documentation pages and document the convention
---
.../{security-authentication.md => authentication-security.md} | 4 ++--
atr/docs/{security-authorization.md => authorization-security.md} | 4 ++--
atr/docs/code-conventions.md | 8 ++++++--
atr/docs/developer-guide.md | 8 ++++----
atr/docs/how-to-contribute.md | 2 +-
atr/docs/index.md | 4 ++--
atr/docs/input-validation.md | 2 +-
7 files changed, 18 insertions(+), 14 deletions(-)
diff --git a/atr/docs/security-authentication.md
b/atr/docs/authentication-security.md
similarity index 98%
rename from atr/docs/security-authentication.md
rename to atr/docs/authentication-security.md
index a2f96a6..79827c9 100644
--- a/atr/docs/security-authentication.md
+++ b/atr/docs/authentication-security.md
@@ -4,7 +4,7 @@
**Prev**: `3.10.` [How to contribute](how-to-contribute)
-**Next**: `3.12.` [Authorization security](security-authorization)
+**Next**: `3.12.` [Authorization security](authorization-security)
**Sections**:
@@ -23,7 +23,7 @@ ATR uses two authentication mechanisms depending on the
access method:
* **Web interface**: ASF OAuth provides browser-based sessions
* **API**: Personal Access Tokens (PATs) authenticate users to obtain
short-lived JSON Web Tokens (JWTs), which then authenticate API requests
-Both mechanisms require HTTPS. Authentication verifies the identity of users,
while authorization (covered in [Authorization
security](security-authorization)) determines what actions they can perform.
+Both mechanisms require HTTPS. Authentication verifies the identity of users,
while authorization (covered in [Authorization
security](authorization-security)) determines what actions they can perform.
## Transport security
diff --git a/atr/docs/security-authorization.md
b/atr/docs/authorization-security.md
similarity index 98%
rename from atr/docs/security-authorization.md
rename to atr/docs/authorization-security.md
index da987a1..617ae3f 100644
--- a/atr/docs/security-authorization.md
+++ b/atr/docs/authorization-security.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: `3.11.` [Authentication security](security-authentication)
+**Prev**: `3.11.` [Authentication security](authentication-security)
**Next**: `3.13.` [Input validation](input-validation)
@@ -20,7 +20,7 @@
## Overview
-ATR uses role-based access control (RBAC) where roles are derived from ASF
LDAP group memberships. Authentication (covered in [Authentication
security](security-authentication)) establishes *who* a user is; authorization
determines *what* they can do.
+ATR uses role-based access control (RBAC) where roles are derived from ASF
LDAP group memberships. Authentication (covered in [Authentication
security](authentication-security)) establishes *who* a user is; authorization
determines *what* they can do.
The authorization model is committee-centric: most permissions are granted
based on a user's relationship to a committee (PMC membership) or project
(committer status).
diff --git a/atr/docs/code-conventions.md b/atr/docs/code-conventions.md
index d690970..1786ec1 100644
--- a/atr/docs/code-conventions.md
+++ b/atr/docs/code-conventions.md
@@ -9,7 +9,7 @@
**Sections**:
* [Python code](#python-code)
-* [Documentation and interfaces](#documentation-and-interfaces)
+* [Documentation and user interfaces](#documentation-and-user-interfaces)
* [HTML](#html)
* [Markdown](#markdown)
* [JavaScript](#javascript)
@@ -258,7 +258,11 @@ This should be adhered to even in contexts where printf
style is usually expecte
This convention is not enforced by any checks. Enforcement is via code review.
See [issue #339](https://github.com/apache/tooling-trusted-releases/issues/339)
for a discussion.
-## Documentation and interfaces
+## Documentation and user interfaces
+
+### Keep documentation filenames consistent with the top level heading
+
+For example, a page with the title "This is an example" should be named
`this-is-an-example.md`.
### Use sentence case for headings, form labels, and submission buttons
diff --git a/atr/docs/developer-guide.md b/atr/docs/developer-guide.md
index 2f66b2d..936e1e6 100644
--- a/atr/docs/developer-guide.md
+++ b/atr/docs/developer-guide.md
@@ -18,8 +18,8 @@
* `3.8.` [Running and creating tests](running-and-creating-tests)
* `3.9.` [Code conventions](code-conventions)
* `3.10.` [How to contribute](how-to-contribute)
-* `3.11.` [Authentication security](security-authentication)
-* `3.12.` [Authorization security](security-authorization)
+* `3.11.` [Authentication security](authentication-security)
+* `3.12.` [Authorization security](authorization-security)
* `3.13.` [Input validation](input-validation)
**Sections**:
@@ -35,8 +35,8 @@ This is a guide for developers of ATR, explaining how to make
changes to the ATR
ATR is security-critical infrastructure for the Apache Software Foundation.
Before contributing, you should familiarize yourself with our security
practices:
-* [Authentication security](security-authentication) - How users authenticate
to ATR via ASF OAuth and API tokens
-* [Authorization security](security-authorization) - The role-based access
control model and LDAP integration
+* [Authentication security](authentication-security) - How users authenticate
to ATR via ASF OAuth and API tokens
+* [Authorization security](authorization-security) - The role-based access
control model and LDAP integration
* [Input validation](input-validation) - Data validation patterns and
injection prevention
For reporting security vulnerabilities, see
[SECURITY.md](https://github.com/apache/tooling-trusted-releases/blob/main/SECURITY.md)
in the repository root.
diff --git a/atr/docs/how-to-contribute.md b/atr/docs/how-to-contribute.md
index a56b8cd..f69d2bd 100644
--- a/atr/docs/how-to-contribute.md
+++ b/atr/docs/how-to-contribute.md
@@ -4,7 +4,7 @@
**Prev**: `3.9.` [Code conventions](code-conventions)
-**Next**: `3.11.` [Authentication security](security-authentication)
+**Next**: `3.11.` [Authentication security](authentication-security)
**Sections**:
diff --git a/atr/docs/index.md b/atr/docs/index.md
index a84e83c..85556b9 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -23,6 +23,6 @@ NOTE: This documentation is a work in progress.
* `3.8.` [Running and creating tests](running-and-creating-tests)
* `3.9.` [Code conventions](code-conventions)
* `3.10.` [How to contribute](how-to-contribute)
- * `3.11.` [Authentication security](security-authentication)
- * `3.12.` [Authorization security](security-authorization)
+ * `3.11.` [Authentication security](authentication-security)
+ * `3.12.` [Authorization security](authorization-security)
* `3.13.` [Input validation](input-validation)
diff --git a/atr/docs/input-validation.md b/atr/docs/input-validation.md
index 744850c..36b303a 100644
--- a/atr/docs/input-validation.md
+++ b/atr/docs/input-validation.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: `3.12.` [Authorization security](security-authorization)
+**Prev**: `3.12.` [Authorization security](authorization-security)
**Next**: (none)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
