Contributor’s Guide

Michael R. Bernstein zopemaven@gmail.com

v0.1.0

Welcome to the AsciiDoctrine developer community! This guide outlines the development environment setup, testing protocols, code quality standards, and package release verification checklist.

Local Development Setup

To establish a reproducible environment, setup a Python 3.10+ virtualenv and install the package in editable mode along with its test and documentation dependencies:

# 1. Clone the repository
git clone https://github.com/webmaven/asciidoctrine.git
cd asciidoctrine

# 2. Initialize virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install in editable development mode
pip install -e ".[test,docs]"

Testing Protocols & Workflow Tiers

We employ a 3-tiered testing strategy to guarantee complete syntactic and semantic compatibility with the AsciiDoc specification while maintaining fast feedback loops.

Tier 1: Rapid Development Loop (Fast / Focused)

Use while iterating on a specific feature, bugfix, or grammar rule:

# Run a targeted test module quietly
pytest tests/test_inlines_parsing.py -q

# Focus on a single test function
pytest tests/test_inlines_parsing.py -k "test_custom_scheme" -q --tb=short

Tier 2: Pre-Commit Check (Core Unit
Local TCK Suite)

Use before committing code. Runs unit tests and the native Python local TCK harness (tests/test_local_tck.py):

# Run all stable tests quietly
pytest -k "not functional" -q --tb=short

Tier 3: Pre-Release Conformance Check (Full Suite
Doctests
Upstream TCK)

Use before tagging releases or pushing release branches:

# 1. Full Pytest suite including all 244 real-world doctests
RUN_DOCTESTS=1 pytest -k "not functional" -q

# 2. Official Upstream Node.js TCK Runner
./run-tck.sh

# 3. TCK Coverage Summary Report
./run-tck-coverage.sh

# 4. Code Quality & Typing Checks
ruff check . && mypy src/asciidoctrine

Standard and Draft TCK Paths

  • Official TCK: Located inside vendor/asciidoc-tck/tests/block/. These are official specification-aligned tests executed via ./run-tck.sh.

  • Local TCK Harness: Located inside tests/tck_harness/tests/. These cover custom additions, draft features, or local spec extensions and are run natively as parametrized pytest tests via tests/test_local_tck.py.

Code Quality & Typing Standards

We strictly enforce consistent code styling and strong static types across the codebase.

1. Linting & Formatting with Ruff

We use Ruff as our fast, all-in-one Python linter and formatter.

# Verify code formatting
ruff format --check .

# Automatically apply formatting
ruff format .

# Check for lint rules and import orders
ruff check .

# Automatically apply lint fixes
ruff check --fix .

2. Strict Type Safety with Mypy

Our type checker runs in strict mode to guarantee compile-time safety and catch structural mismatches early.

# Run strict static type checking
mypy src/asciidoctrine

Pre-Release Verification Checklist

Before releasing any package version to PyPI, follow this sequential checklist to prevent regressions, formatting lints, and setup failures:

  1. Local Test & Lint Execution:

  • Ensure Ruff linter and formatter are completely happy.

  • Ensure the Mypy strict type-checker passes cleanly.

  • Run the full test suite locally with coverage (using -n0 to disable multi-processing clashes):

```bash pytest -n0 –cov=src –cov-report=term-missing -k “not functional”

```

  • Run the TCK suite locally and check for 100% compliance.

  1. Verify Version Coherence:

  • Verify that the exact target version is aligned in pyproject.toml (under version = "...").

  • Verify that the exact same string matches __version__ = "..." inside src/asciidoctrine/__init__.py.

  • Ensure the new release section is documented at the top of CHANGELOG.adoc.

  1. Verify Documentation and Sandboxes:

  • Rebuild HTML documentation locally to ensure zero errors:

```bash sphinx-build -a -E -b html docs docs/_build/html

```

  1. Verify GHA Status on main:

  • Push release branches to GitHub and verify that all GitHub Actions jobs (including Pyodide runs, document builders, and linters) succeed cleanly with a green checkmark before creating the PyPI release.