Contributing to ArchMAP

Thanks for contributing! Please read our Code of Conduct first.

Prerequisites

• Python >= 3.11
• pip >= 23
• Git

Setup

git clone https://github.com/Kaua-KGzin/ArchMAP
cd ArchMAP
python -m pip install -e ".[dev]"

Running the tool locally

# Analyze a project
archmap analyze <path>

# Start the interactive Web UI
archmap serve <path>

# Compare two git refs
archmap diff HEAD~5 HEAD

Running tests

pytest                       # all tests with coverage
pytest tests/test_cli.py     # single module
pytest -k "parser"           # filter by name

Running lint

ruff check .

Building the Windows executable (PyInstaller)

pip install pyinstaller
pyinstaller archmap.spec
# Output: dist/archmap.exe

Branching model

• main: stable branch only
• dev: integration branch for upcoming release
• feat/*: one feature per branch
• feature/*: legacy alias supported
• fix/*: bugfix branches
• docs/*: documentation-only changes
• release/*: stabilization and release prep

Flow: feat/* -> dev -> release/* -> main

Development checklist before opening a PR

1. Branch from dev (or main only for urgent production fixes).
2. Implement changes with tests.
3. Run quality gates:

ruff check .
pytest
archmap analyze . --format both --out .codeatlas/local-graph.json --out-mermaid .codeatlas/local-graph.mmd --include-cytoscape
python -m archmap.cli.main analyze . --fail-on-risks

1. Update CHANGELOG.md, README.md, or ROADMAP.md if behavior changes.
2. Open a PR using the repository template.

Coding guidelines

• Keep modules focused and composable.
• Prefer explicit data contracts for analyzer outputs (typed dicts).
• Add tests for any parser/analyzer/exporter behavior changes.
• Preserve CLI compatibility unless a major release justifies breaking changes.

Original distribution attribution

ArchMAP is originally distributed by Kaua Gabriel (Kaua-KGzin).

When redistributing source code or binaries, preserve: - LICENSE - NOTICE.md