Skip to main content

Contributing

Contributing to Doc Gen

Review Checklist

Develop project-structure features with evidence that scanning, rendering, and persistence remain correctly separated.

Commandmake check

Category

Developer Guide

Quick Command

scope -> implement -> validate -> document -> hand off
qualitytestsgenerationdry-runpre-commit
Quality Helper
make check
Package Runtime
Python 3.9+
Read-Only Commands
print and analyze
Writable Command
generate

Overview​

Keep CLI interaction under app/doc_gen/cli, reusable structure behavior under app/doc_gen/core/structure, Markdown construction in renderers, and file persistence in writers. Make selected targets and outputs explicit.

Contribution Workflow

Workflow Timeline

1
Trace the structure flow
Follow CLI and configuration resolution through scanning, profiles, metadata, analysis, rendering, writing, and presentation.
completed
2
Define the output contract
State the selected target, ignored content, returned output, allowed file write, dry-run behavior, and failures.
completed
3
Implement with tests
Separate read-only computation from persistence and cover successful, failing, and dry-run paths.
current
4
Run widening validation
Run focused tests, hook checks, make check, and the complete suite.
pending
5
Synchronize documentation
Update commands, profiles, configuration, outputs, dry-run, troubleshooting, and architecture as needed.
pending
6
Prepare the handoff
Report affected files, output-safety evidence, validation results, limits, and intentional non-changes.
pending

Implementation Standards

Before You Begin

  • Resolve target and outputRequired

    Determine repository input and output document before generation begins.

  • Keep read-only commands read-onlyRequired

    Print and analyze must never create or update project documents.

  • Keep generate narrowRequired

    Only the resolved output document may be written.

  • Protect dry-runRequired

    Dry-run may scan and render but must not create directories, write files, or invoke the writer.

  • Preserve ignore behaviorRequired

    Apply built-in and configured exclusions consistently across print, analyze, and generate.

  • Document public contractsRequired

    Synchronize options, profiles, output paths, examples, failures, and recovery guidance.

Quality Gates

Contributor validation
bash
# Focused examples
python -m pytest tests/cli
python -m pytest tests/test_dry_run.py

# Complete validation

python -m pytest
make check

# Hook validation

make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Final Review Checklist

Before You Begin

  • Scope is focusedRequired

    Every changed file supports the structure contract, tests, or documentation.

  • Read-only behavior is provenRequired

    Print, analyze, and dry-run leave project files unchanged.

  • Generation is preciseRequired

    Only the requested document is written and unrelated documentation remains untouched.

  • Quality results are recordedRequired

    Focused tests, full tests, formatting, lint, and relevant builds have explicit outcomes.

  • Release actions remain separateRequired

    Versions, changelogs, tags, pushes, and publication are untouched unless explicitly requested.

Related Commands

Commands commonly used together with this command.

Testing

Validate output and dry-run contracts.

Configuration

Preserve profiles, targets, outputs, and ignore rules.