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 25f82ca Fix Markdown issues detected by linting
25f82ca is described below
commit 25f82caaf2d53ae17f1b2896e4c497807eea18a1
Author: Sean B. Palmer <[email protected]>
AuthorDate: Wed Jan 21 19:52:05 2026 +0000
Fix Markdown issues detected by linting
---
.github/PULL_REQUEST_TEMPLATE.md | 2 +-
BUILD.md | 86 +++++++++++++++++++++-------------------
CONTRIBUTING.md | 17 ++++++--
DEVELOPMENT.md | 27 ++++++++-----
GOVERNANCE.md | 6 +--
README.md | 6 +--
SUPPORT.md | 2 +-
atr/docs/how-to-contribute.md | 12 +++---
atr/docs/running-the-server.md | 26 ++++++------
9 files changed, 102 insertions(+), 82 deletions(-)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 2168dcb..d5b0c1f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,4 @@
-## Pull Request Summary
+## Pull Request Summary <!-- markdownlint-disable-line MD041 -->
**Meaningful subject (required):**
diff --git a/BUILD.md b/BUILD.md
index b6c237e..b39819f 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -11,6 +11,7 @@ This guide covers building ATR and its components. For
development setup, see [D
- **Python 3.13** - Required runtime
Install on Alpine Linux:
+
```shell
apk add cmark curl git make mkcert@testing
curl -LsSf https://astral.sh/uv/install.sh | env
UV_INSTALL_DIR="/usr/local/bin" sh
@@ -18,6 +19,7 @@ uv python install 3.13
```
Install on macOS (Homebrew):
+
```shell
brew install cmark mkcert
curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -54,6 +56,7 @@ docker compose up --build
```
The compose configuration:
+
- Mounts `atr/` for live code changes
- Enables test mode (`ALLOW_TESTS=1`)
- Exposes port 8080
@@ -67,6 +70,7 @@ make docs
```
This command:
+
1. Validates the table of contents structure
2. Generates navigation links between pages
3. Converts Markdown to HTML using cmark
@@ -175,64 +179,65 @@ sh tests/run-e2e.sh
### Build Targets
-| Target | Description |
-|--------|-------------|
-| `build` | Alias for `build-alpine` |
-| `build-alpine` | Build the Alpine-based container |
-| `build-bootstrap` | Build Bootstrap assets |
-| `build-docs` | Build documentation without validation |
-| `build-playwright` | Build Playwright test container |
-| `build-ts` | Compile TypeScript |
+| Target | Description |
+| ------------------ | -------------------------------------- |
+| `build` | Alias for `build-alpine` |
+| `build-alpine` | Build the Alpine-based container |
+| `build-bootstrap` | Build Bootstrap assets |
+| `build-docs` | Build documentation without validation |
+| `build-playwright` | Build Playwright test container |
+| `build-ts` | Compile TypeScript |
### Run Targets
-| Target | Description |
-|--------|-------------|
-| `serve` | Run server with standard config |
-| `serve-local` | Run server with debug and test mode |
-| `run-alpine` | Run the Alpine container |
-| `run-playwright` | Run Playwright tests (fast) |
-| `run-playwright-slow` | Run Playwright tests (full) |
+| Target | Description |
+| ----------------------- | ----------------------------------- |
+| `serve` | Run server with standard config |
+| `serve-local` | Run server with debug and test mode |
+| `run-alpine` | Run the Alpine container |
+| `run-playwright` | Run Playwright tests (fast) |
+| `run-playwright-slow` | Run Playwright tests (full) |
### Dependency Targets
-| Target | Description |
-|--------|-------------|
-| `sync` | Install production dependencies |
-| `sync-all` | Install all dependencies including dev |
-| `update-deps` | Update and lock dependencies |
+| Target | Description |
+| ------------- | -------------------------------------- |
+| `sync` | Install production dependencies |
+| `sync-all` | Install all dependencies including dev |
+| `update-deps` | Update and lock dependencies |
### Code Quality Targets
-| Target | Description |
-|--------|-------------|
-| `check` | Run all pre-commit checks |
-| `check-light` | Run lightweight checks |
-| `check-heavy` | Run comprehensive checks |
-| `check-extra` | Run interface ordering checks |
+| Target | Description |
+| -------------- | ------------------------------ |
+| `check` | Run all pre-commit checks |
+| `check-light` | Run lightweight checks |
+| `check-heavy` | Run comprehensive checks |
+| `check-extra` | Run interface ordering checks |
### Utility Targets
-| Target | Description |
-|--------|-------------|
-| `certs` | Generate self-signed certificates |
-| `certs-local` | Generate mkcert certificates |
-| `docs` | Build and validate documentation |
-| `generate-version` | Generate version.py |
-| `commit` | Add, commit, pull, push workflow |
-| `ipython` | Start IPython shell with project |
+| Target | Description |
+| ------------------ | ---------------------------------- |
+| `certs` | Generate self-signed certificates |
+| `certs-local` | Generate mkcert certificates |
+| `docs` | Build and validate documentation |
+| `generate-version` | Generate version.py |
+| `commit` | Add, commit, pull, push workflow |
+| `ipython` | Start IPython shell with project |
## Configuration Variables
The Makefile supports these variables:
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `BIND` | `127.0.0.1:8080` | Server bind address |
-| `IMAGE` | `tooling-trusted-release` | Container image name |
-| `STATE_DIR` | `state` | State directory path |
+| Variable | Default | Description |
+| ----------- | ------------------------- | --------------------- |
+| `BIND` | `127.0.0.1:8080` | Server bind address |
+| `IMAGE` | `tooling-trusted-release` | Container image name |
+| `STATE_DIR` | `state` | State directory path |
Example:
+
```shell
make serve-local BIND=0.0.0.0:8080
```
@@ -240,8 +245,9 @@ make serve-local BIND=0.0.0.0:8080
## CI/CD
The GitHub Actions workflow (`.github/workflows/build.yml`) runs:
+
1. Pre-commit checks
2. Playwright browser tests
3. Container build verification
-See the workflow file for details on the CI environment.
\ No newline at end of file
+See the workflow file for details on the CI environment.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1231172..06ec8f0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,21 +18,24 @@ For detailed ASF policies, commit message guidelines, and
security consideration
## Development Setup
1. **Fork and clone** the repository:
+
```shell
git clone https://github.com/YOUR_USERNAME/tooling-trusted-releases.git
cd tooling-trusted-releases
```
2. **Install dependencies** (includes pre-commit, dev tools, and test
dependencies):
+
```shell
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
-
+
# Install all dependencies
uv sync --frozen --all-groups
```
3. **Set up pre-commit hooks:**
+
```shell
uv run pre-commit install
```
@@ -42,6 +45,7 @@ For detailed ASF policies, commit message guidelines, and
security consideration
## Pull Request Workflow
1. **Create a branch** with a descriptive name:
+
```shell
git checkout -b fix-typo-in-docs
```
@@ -49,6 +53,7 @@ For detailed ASF policies, commit message guidelines, and
security consideration
2. **Make your changes** following our [code
conventions](https://release-test.apache.org/docs/code-conventions)
3. **Run checks** before committing:
+
```shell
make check
```
@@ -56,6 +61,7 @@ For detailed ASF policies, commit message guidelines, and
security consideration
4. **Commit** with a clear message (see [commit style](#commit-message-style)
below)
5. **Push** your branch:
+
```shell
git push origin your-branch-name
```
@@ -73,19 +79,22 @@ For detailed ASF policies, commit message guidelines, and
security consideration
Use clear, concise commit messages:
**Format:**
+
- First line: imperative mood, sentence case, 50-72 characters
- No period at the end
- Use articles ("Fix a bug" not "Fix bug")
**Good examples:**
-```
+
+```text
Add distribution platform validation to the compose phase
Fix a bug with sorting version numbers containing release candidates
Update dependencies
```
**Poor examples:**
-```
+
+```text
fixed stuff
Updated the code.
refactoring vote resolution logic
@@ -150,4 +159,4 @@ ATR's primary goal is to prevent supply chain attacks. When
contributing:
## Alternative: Email Patches
-If you prefer not to use GitHub, you can [email
patches](https://lists.apache.org/[email protected]) using
standard Git patch formatting.
\ No newline at end of file
+If you prefer not to use GitHub, you can [email
patches](https://lists.apache.org/[email protected]) using
standard Git patch formatting.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index ddcaa4d..b4aba2c 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -61,6 +61,7 @@ The first build takes several minutes. Subsequent runs are
faster due to caching
Visit [`https://127.0.0.1:8080/`](https://127.0.0.1:8080/) and accept the
self-signed certificate.
The container:
+
- Runs in test mode (`ALLOW_TESTS=1`) with mock authentication
- Mounts `atr/` for live code changes without rebuilding
- Auto-reloads when files change
@@ -103,7 +104,7 @@ make serve-local
We recommend using `localhost.apache.org`, which requires adding to
`/etc/hosts`:
-```
+```text
127.0.0.1 localhost.apache.org
```
@@ -120,43 +121,47 @@ Alternatively, use
[`https://127.0.0.1:8080/`](https://127.0.0.1:8080/) without
## Development Workflow
1. **Set up pre-commit hooks:**
+
```shell
uv run pre-commit install
```
2. **Run code checks:**
+
```shell
make check # Full checks
make check-light # Quick checks
```
3. **Run tests:**
+
```shell
sh tests/run-playwright.sh # Browser tests with Docker Compose
sh tests/run-e2e.sh # End-to-end tests
```
4. **Build documentation:**
+
```shell
make docs
```
## Key Make Targets
-| Target | Description |
-|--------|-------------|
-| `make serve-local` | Run server locally with debug mode |
-| `make check` | Run all pre-commit checks |
-| `make check-light` | Run quick pre-commit checks |
-| `make docs` | Build documentation |
-| `make build-alpine` | Build the Alpine container |
-| `make run-playwright` | Run browser tests |
+| Target | Description |
+| ----------------------- | ---------------------------------- |
+| `make serve-local` | Run server locally with debug mode |
+| `make check` | Run all pre-commit checks |
+| `make check-light` | Run quick pre-commit checks |
+| `make docs` | Build documentation |
+| `make build-alpine` | Build the Alpine container |
+| `make run-playwright` | Run browser tests |
See [BUILD.md](BUILD.md) for the complete list of build targets.
## Project Structure
-```
+```text
tooling-trusted-releases/
├── atr/ # Main application source code
│ ├── api/ # API endpoints
@@ -214,4 +219,4 @@ Developers without LDAP credentials can cache session
information:
2. Press the "Cache me!" button
3. Restart the server to clear the authorization cache if needed
-This writes your session to the ATR state directory, which is consulted
instead of LDAP. This feature only works in debug mode (`make serve-local`).
\ No newline at end of file
+This writes your session to the ATR state directory, which is consulted
instead of LDAP. This feature only works in debug mode (`make serve-local`).
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index 46f9395..3ef336b 100644
--- a/GOVERNANCE.md
+++ b/GOVERNANCE.md
@@ -19,11 +19,11 @@ ASF Tooling is an ASF initiative launched in 2025,
responsible for:
## Decision Making
-*TODO: Document the decision-making process for ATR.*
+TODO: Document the decision-making process for ATR.
## Roles and Responsibilities
-*TODO: Document roles (committers, PMC members, contributors, etc.)*
+TODO: Document roles (committers, PMC members, contributors, etc.)
## Communication
@@ -43,4 +43,4 @@ All participants in the ATR community are expected to follow
the [ASF Code of Co
---
-*TODO: This document is a placeholder. Full governance details will be added
as the project structure is formalized.*
\ No newline at end of file
+TODO: This document is a placeholder. Full governance details will be added as
the project structure is formalized.
diff --git a/README.md b/README.md
index bf7f3a7..383c9d7 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,7 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for more options
including running without
## Documentation
| Document | Description |
-|----------|-------------|
+| -------- | ----------- |
| [DEVELOPMENT.md](DEVELOPMENT.md) | Quick start guide for developers |
| [BUILD.md](BUILD.md) | Build instructions and Make targets |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute code |
@@ -62,7 +62,7 @@ Community feedback is encouraged! If you are an ASF committer
or contributor int
2. **Introduce yourself** on the development mailing list:
📧 [[email protected]](mailto:[email protected])
-
+
Subscribe by sending email with empty subject and body to
[[email protected]](mailto:[email protected]) and
replying to the automated response (per the [ASF mailing list
how-to](https://www.apache.org/foundation/mailinglists)).
3. **Share ideas or file issues:**
@@ -90,4 +90,4 @@ This project is licensed under the [Apache License, Version
2.0](LICENSE).
---
*Part of the [Apache Tooling Initiative](https://tooling.apache.org/).*
-For more information about the ASF, visit https://www.apache.org/.
\ No newline at end of file
+For more information about the ASF, visit https://www.apache.org/.
diff --git a/SUPPORT.md b/SUPPORT.md
index 280fa52..e415dc8 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -52,4 +52,4 @@ The alpha test deployment is available at:
**https://release-test.apache.org/**
---
-*TODO: This document is a placeholder. Additional support information will be
added as the project matures.*
\ No newline at end of file
+*TODO: This document is a placeholder. Additional support information will be
added as the project matures.*
diff --git a/atr/docs/how-to-contribute.md b/atr/docs/how-to-contribute.md
index 71f9bfa..b97bd2e 100644
--- a/atr/docs/how-to-contribute.md
+++ b/atr/docs/how-to-contribute.md
@@ -20,10 +20,10 @@ For the contribution workflow, see
**[CONTRIBUTING.md](https://github.com/apache
That guide covers:
-- Development setup
-- Pull request workflow
-- Running tests
-- Code standards summary
+* Development setup
+* Pull request workflow
+* Running tests
+* Code standards summary
**IMPORTANT:** New contributors must introduce themselves on [the development
mailing list](mailto:[email protected]) first, to deter spam. Please do
not submit a PR until you have introduced yourself.
@@ -41,7 +41,7 @@ We follow a consistent style for commit messages. The first
line (subject line)
**Good examples:**
-```
+```text
Add distribution platform validation to the compose phase
Fix a bug with sorting version numbers containing release candidates
Move code to delete releases to the storage interface
@@ -50,7 +50,7 @@ Update dependencies
**Poor examples:**
-```
+```text
fixed stuff
Updated the code.
refactoring vote resolution logic
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index 7d90e7b..2f37dc8 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -19,10 +19,10 @@ For step-by-step setup instructions, see
**[DEVELOPMENT.md](https://github.com/a
That guide covers:
-- Prerequisites and platform-specific installation
-- Running with Docker Compose (recommended)
-- Running directly with uv and mkcert
-- Development workflow and troubleshooting
+* Prerequisites and platform-specific installation
+* Running with Docker Compose (recommended)
+* Running directly with uv and mkcert
+* Development workflow and troubleshooting
The rest of this page provides deeper technical context for how the server
works.
@@ -36,8 +36,8 @@ ATR is a Python application based on
[ASFQuart](https://github.com/apache/infras
**Trade-offs:**
-- _Container_: isolated, includes all tools; slower startup, certificate trust
setup
-- _Direct_: fast iteration, auto-trusted certs; manual dependency setup
+* _Container_: isolated, includes all tools; slower startup, certificate trust
setup
+* _Direct_: fast iteration, auto-trusted certs; manual dependency setup
**Important:** Do not run both methods simultaneously - they share the same
state directory and will conflict.
@@ -59,7 +59,7 @@ We exclude `localhost` to avoid [DNS resolution issues noted
in RFC 8252](https:
ATR serves on multiple hosts, but we recommend using `localhost.apache.org`
consistently. This requires an `/etc/hosts` entry:
-```
+```text
127.0.0.1 localhost.apache.org
```
@@ -67,12 +67,12 @@ ATR serves on multiple hosts, but we recommend using
`localhost.apache.org` cons
### Environment variables
-- `ALLOW_TESTS=1`: Enable test mode with mock authentication
-- `APP_HOST`: Hostname for the application
-- `BIND`: Address and port to bind (default: `127.0.0.1:8080`)
-- `LDAP_BIND_DN`: LDAP bind DN for rsync writes
-- `LDAP_BIND_PASSWORD`: LDAP bind password
-- `SSH_HOST`: SSH host for rsync operations
+* `ALLOW_TESTS=1`: Enable test mode with mock authentication
+* `APP_HOST`: Hostname for the application
+* `BIND`: Address and port to bind (default: `127.0.0.1:8080`)
+* `LDAP_BIND_DN`: LDAP bind DN for rsync writes
+* `LDAP_BIND_PASSWORD`: LDAP bind password
+* `SSH_HOST`: SSH host for rsync operations
### Startup behavior
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
