Internal Change Guide

Use this page when a change goes below the maintainer-facing APIs listed in the package reference. Internal modules are implementation areas, not stable public APIs, but each area has a clear owner and test surface.

Start from the behavior you need to change. Read the facade first, then the support modules and tests named in the same row. Prefer adding or adjusting a small test before editing support code.

Change Map

Behavior	Start With	Internal Area	Tests
Expand upstream template source into translator-friendly source	template_transform.py	_template_transform/	tests/unit/test_template_transform.py, tests/unit/test_rewrite_rules.py
Science Europe sentence rewrite or branch-fragment cleanup	_template_transform/science_europe.py	profile.py, science_europe_balanced_rules.py, science_europe_unbalanced_rules.py, rewrite_rules.py	tests/unit/test_template_transform.py, tests/unit/test_rewrite_rules.py, render regression
Translation Markdown parse/render format	translation_tree.py	_translation_tree/document.py, _translation_tree/metadata.py, _translation_tree/outline.py	tests/unit/test_translation_tree.py, CLI tests under tests/infra/
Translation unit extraction, placeholder handling, or Jinja safety	translation_tree.py	extraction.py, placeholders.py, syntax.py, tree_audit.py	tests/unit/test_translation_tree.py, tests/unit/test_markers.py
Translator-facing source-fragment regression guard	source_quality_rules.py	source_text.py, tree_audit.py	tests/unit/test_source_quality_rules.py, tests/unit/test_translation_tree.py
Exact-source synchronization between template versions	_translation_tree/merge.py, translation_repository/	scripts/ci/create_translation_migration_prs.py, scripts/ci/check_translation_migration_status.py	tests/unit/test_translation_tree.py, tests/infra/test_translation_migration_prs.py
Read-only wording consistency across version branches	translation_repository/consistency.py	scripts/ci/report_translation_consistency.py	tests/unit/test_translation_consistency.py
Downstream sync/v* branch refresh	scripts/ci/sync_translation_version_branches.py	examples/github-actions/document_template_translation_sync.yml and version policy config	tests/infra/test_translation_version_branch_sync.py, tests/infra/test_github_workflows.py
Downstream repository documentation templates	examples/translation-repository/	docs/translation-repository-templates.md	tests/infra/test_documentation_site.py
DSW runtime compatibility and unsupported metamodel probes	dsw_compat.py, config/dsw-compat.yml	scripts/ci/discover_dsw_compat.py, scripts/ci/create_dsw_compat_pr.py	tests/unit/test_dsw_compat.py, tests/infra/test_ci_control_helpers.py
Clean scaffold artifact generation and release assets	scripts/ci/upstream_template_artifacts.py	compat_ledger.py, scripts/ci/publish_clean_scaffold_releases.py	tests/unit/test_compat_ledger.py, tests/infra/test_stage_release_assets.py
Render preview or regression behavior	workflow.py, render_project.py	_regression/, api.py, fixture_generator.py, html_diff.py	tests/unit/test_workflow.py, tests/unit/test_regression_artifacts.py, tests/unit/test_render_project.py, tests/unit/test_fixture_generator.py
GitHub Actions template wiring	examples/github-actions/	Installed CLI commands in src/dsw_document_template_tool/cli/ and helper scripts in scripts/ci/	tests/infra/test_github_workflows.py, tests/infra/test_cli_entrypoints.py

Editing Rules

• Keep user-facing CLI commands declared in pyproject.toml and implemented under src/dsw_document_template_tool/cli/.

• Keep GitHub Actions YAML as orchestration. Parsing, branch selection, migration policy, release staging, and GitHub API behavior belong in Python.

• Keep generated files under ignored output roots. If a generated file needs to be reviewed, turn it into a fixture or release artifact intentionally.

• Update docs and Sphinx API pages in the same commit as behavior changes.

• When parser or translation-tree behavior changes, run unit tests, migration dry-run, and at least one preview/regression path before trusting the change.