Contributing¶
Thank you for your interest in contributing to NetTap. This page provides a summary of the contribution workflow. For full details, see the CONTRIBUTING.md file in the repository.
Quick Start¶
- Fork the repository on GitHub
- Clone your fork:
- Add upstream remote:
- Create a feature branch from
develop: - Make your changes, commit, and push
- Open a Pull Request targeting
develop
Branch Model¶
| Branch | Purpose |
|---|---|
main |
Protected. Only receives merges at major releases. Never push directly. |
develop |
Integration branch. All feature branches merge here via PR. |
phase-N/description |
Feature branches. All work happens here. |
infra/description |
Cross-cutting infrastructure work. |
chore/description |
Maintenance tasks. |
Commit Convention¶
This project uses Conventional Commits. Every commit must follow this format:
Types: feat, fix, docs, refactor, test, chore, ci, perf, style
Examples:
feat(bridge): add netplan persistence for br0
fix(daemon): handle OpenSearch connection timeout
test(storage): add coverage for disk threshold logic
docs(readme): update architecture diagram
chore(docker): pin Malcolm images to v26.02.0
Rules:
- Use imperative mood ("add" not "added")
- No period at the end of the subject line
- Keep subject under 72 characters
- One logical change per commit
Pull Request Process¶
- Target
develop--- nevermain - Ensure your branch is up to date with
develop - All CI checks must pass before review
- Fill out the PR template completely
- Request a review from
@EliasMarine - Address review feedback with new commits (do not force-push during review)
- After merge, delete your feature branch
PR Size¶
- Keep PRs under ~400 lines of diff when possible
- Break large changes into smaller, reviewable PRs
- Each PR should represent one logical unit of work
Code Style¶
Python (daemon)¶
- Linter/formatter: Ruff
- Follow PEP 8
- Type hints for function signatures
- Google-style docstrings
# Same ruff version CI pins; formatter output differs between releases
uvx ruff@0.17.3 check daemon/
uvx ruff@0.17.3 format daemon/
TypeScript / Svelte (web)¶
- Linter: ESLint
- Type checking:
svelte-check - TypeScript for all new code
Shell Scripts¶
- Linter: ShellCheck
- Use
set -euo pipefail - Quote all variables
- Use
#!/usr/bin/env bash
Testing Requirements¶
- All existing tests must pass before submitting a PR
- New features must include tests
- Bug fixes should include a regression test
See Testing for details on running the test suite.
Reporting Issues¶
- Bugs: Open a GitHub Issue with reproduction steps
- Features: Open a Discussion or Issue describing the use case
- Security: See SECURITY.md for responsible disclosure