Contributing

Contributing

How to Contribute

1. Fork the repository
2. Clone: git clone https://github.com/YOUR_USERNAME/Apotropaios-Firewall-Manager-Python-Variant.git
3. Setup: make dev-setup && source .venv/bin/activate
4. Branch: git checkout -b feature/your-feature develop
5. Develop (follow coding standards below)
6. Test: make check (mypy --strict + 322 tests -- MUST pass)
7. Security: make security-scan (6 checks -- MUST pass)
8. PR: Submit against develop branch

Quality Gates (Non-Negotiable)

• make typecheck -- mypy --strict with zero errors across all 35 files
• make test -- 322/322 tests passing, no skips, no xfail
• make security-scan -- All 6 static pattern checks passing

Coding Standards

1. Full type annotations on every function (params + return)
2. from __future__ import annotations at top of every module
3. Google-style docstrings on all public functions/classes
4. Module headers with File, Project, Synopsis, Description, Notes, Version
5. Never shell=True in subprocess -- always list-form
6. Always capture stderr on subprocess calls
7. Validate all input through core/validation.py before use
8. Atomic writes for persistent data (temp → os.replace())
9. Thread safety via threading.Lock on shared mutable state
10. No circular imports -- strict 5-layer dependency ordering
11. No stubs or placeholders -- every function fully implemented

Testing Requirements

• New feature → unit tests (normal + error paths)
• Bug fix → regression test that fails before fix
• New validator → valid AND invalid input tests
• New CLI command → subprocess integration test
• New backend → MockBackend-based tests
• New backend command-composition or fail-closed path → direct builder/mapper test (see tests/unit/test_backend_validation.py)
• New workflow or issue template → covered by the CI meta-suite (tests/ci/test_workflows.py)

The suite has four tiers: unit (tests/unit/), integration (tests/integration/), security (tests/security/), and CI meta-tests (tests/ci/) that validate the workflow and issue-template files as data.

Continuous Integration

Five workflows run on every pull request and must pass before merge: ci.yml (lint, strict typing, test matrix on Python 3.12 and 3.13 with coverage, security tests, and consistency checks), security.yml (bandit SAST plus the security suite), codeql.yml (CodeQL semantic analysis), docs-validate.yml (the two validation scripts plus the CI meta-suite), and release.yml (tag-versus-version gate, build, checksums, and release publishing on version tags).

Two scripts back the consistency gates and run locally:

python3 scripts/check_version_consistency.py   # every version location agrees
python3 scripts/validate_docs.py               # documentation matches source

The first verifies that every version-bearing file matches the canonical VERSION. The second verifies documentation accuracy against source -- line counts, suite-total test counts, command counts, the no-version-identifiers-outside-changelogs policy, and internal links. Run both before opening a pull request.

Workflow action pins follow a fixed standard (checkout@v6, setup-python@v6, upload-artifact@v6, download-artifact@v6, codeql-action@v4), enforced by the CI meta-suite. PyYAML is a required CI dependency alongside pytest: without it the CI meta-suite is silently excluded from collection.

Reporting Issues

File issues through the structured forms: Bug Report, Feature Request, Documentation Issue, and Platform / Backend Support Request. Blank issues are disabled. Security vulnerabilities go through the private disclosure process in the security policy, never as a public issue.

Commit Format

feat(nftables): add rate limiting support
fix(firewalld): reset iterates ALL zones
docs(developer): expand validation detail
test(security): add hostname injection tests

Known Pitfalls (Avoid These)

Code	Pitfall	Prevention
PY-003	CLI handlers scaffolded but never wired	Wire immediately when engine module completes
PY-004	Tests pass with dead CLI code	Use subprocess integration tests
PY-005	pip vs pip3	Always pip3
PY-007	Post-shutdown console noise	Remove console handler before shutdown marker
PY-008	Status shows rules instead of service state	Status = service state. List = rules.
PY-009	pip install discovers data/ as package	Explicit package discovery in pyproject.toml

Security Contributions

DO NOT report vulnerabilities through public issues. See Security Policy for coordinated disclosure process. Security fix PRs should include CWE reference, regression test, and SECURITY.md update.