Lewati ke konten utama

Contributing

Contributing to Doc Gen

Review Checklist

Kembangkan project-structure features dengan bukti bahwa scanning, rendering, dan persistence tetap terpisah dengan benar.

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 dan analyze
Writable Command
generate

Overview​

Pertahankan CLI interaction di app/doc_gen/cli, reusable structure behavior di app/doc_gen/core/structure, Markdown construction dalam renderers, dan file persistence dalam writers. Nyatakan selected targets dan outputs dengan jelas.

Contribution Workflow

Workflow Timeline

1
Telusuri structure flow
Ikuti CLI dan configuration resolution melalui scanning, profiles, metadata, analysis, rendering, writing, dan presentation.
completed
2
Tentukan output contract
Nyatakan selected target, ignored content, returned output, allowed file write, dry-run behavior, dan failures.
completed
3
Implementasikan bersama tests
Pisahkan read-only computation dari persistence dan uji success, failure, serta dry-run paths.
current
4
Jalankan widening validation
Jalankan focused tests, hook checks, make check, dan complete suite.
pending
5
Sinkronkan documentation
Update commands, profiles, configuration, outputs, dry-run, troubleshooting, dan architecture sesuai kebutuhan.
pending
6
Siapkan handoff
Laporkan affected files, output-safety evidence, validation results, limitations, dan intentional non-changes.
pending

Implementation Standards

Before You Begin

  • Resolve target dan outputRequired

    Tentukan repository input dan output document sebelum generation dimulai.

  • Pertahankan read-only commandsRequired

    Print dan analyze tidak boleh membuat atau meng-update project documents.

  • Batasi generateRequired

    Hanya resolved output document yang boleh ditulis.

  • Lindungi dry-runRequired

    Dry-run boleh melakukan scan dan render, tetapi tidak boleh membuat directories, menulis files, atau memanggil writer.

  • Pertahankan ignore behaviorRequired

    Terapkan built-in dan configured exclusions secara konsisten pada print, analyze, dan generate.

  • Dokumentasikan public contractsRequired

    Sinkronkan options, profiles, output paths, examples, failures, dan 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 tetap focusedRequired

    Setiap changed file mendukung structure contract, tests, atau documentation.

  • Read-only behavior terbuktiRequired

    Print, analyze, dan dry-run tidak mengubah project files.

  • Generation bersifat preciseRequired

    Hanya requested document yang ditulis dan unrelated documentation tetap tidak berubah.

  • Quality results dicatatRequired

    Focused tests, full tests, formatting, lint, dan relevant builds memiliki explicit outcomes.

  • Release actions tetap terpisahRequired

    Versions, changelogs, tags, pushes, dan publication tidak berubah kecuali diminta secara explicit.

Related Commands

Commands commonly used together with this command.

Testing

Validasi output dan dry-run contracts.

Configuration

Pertahankan profiles, targets, outputs, dan ignore rules.