Skip to content
astrapatchastrapatch

ContributeContributor handbook

Building astrapatch, together.

How to join the project, the rules that keep it credible, and how a change goes from idea to merge. Beginners are welcome; start with the learning roadmap if you are new to the field.

PDFContribution GuideHow to contribute, the standards every change follows, and the pre-submission checklist.PDF · 15 pagesDownload Contribution GuidePDFBeginner RoadmapA self-paced path from your first terminal command to your first astrapatch contribution.PDF · 13 pagesDownload Beginner Roadmap

01Join the project

Request contributor access.

Send a short introduction to the maintainers. Requests are reviewed by hand, and approved contributors are invited to the astrapatch GitHub organization.

Emailcontribute@astrapatch.online
SubjectContributor access: <your GitHub username>
Write the email

What to include

GitHub username
Required. This is the account that will be invited to the organization.
Name and affiliation
Your name, and your university, lab or company if you have one. Independent contributors are welcome.
Area of interest
Analyzers, remediation, simulation and scenarios, policies, research, or documentation.
Relevant experience
Links where possible: repositories, papers, flight software or security work.
Why astrapatch
Why you are interested in the project and what you would like to build or improve.

Requirements

  • A GitHub account with two-factor authentication enabled.
  • You have read the contribution guide and the Code of Conduct, and agree to follow them.
  • You agree that your contributions are licensed under the Apache License 2.0.
  • You only submit work you have the right to contribute.

02The rules

What every change must respect.

  • P1

    Patches are untrusted

    Whatever produced a candidate, it must pass verification and human review.

  • P2

    Policies are deterministic

    Same evidence, same answer. Model output can never override a rule.

  • P3

    Unknown is not pass

    Missing data makes a verdict inconclusive. It is never rounded up.

  • P4

    Evidence over confidence

    Every result is backed by artifacts a reviewer can inspect and reproduce.

  • P5

    Humans approve

    astrapatch classifies candidates for review. It has no deploy step.

  • P6

    Local first, no lock-in

    Runs offline, with no dependency on a single model, cloud or vendor.

  • P7

    Wrap, do not reinvent

    Adapters integrate existing analyzers and simulators.

  • P8

    Say only what is true

    Never describe planned work as shipped, or claim certification or endorsement.

Do

  • Mark work as planned, experimental or available, and keep status tables current
  • Label demo, fictional and illustrative material
  • State limits plainly, such as copies are not a sandbox
  • Cite real sources for research claims

Do not

  • Describe planned features as implemented
  • Add metrics or benchmarks without real data
  • Claim certification or endorsement by any agency
  • Imply that passing verification means flight safety

03Workflow

From idea to merged change.

  1. 01

    Request access

    Email the maintainers with your GitHub username, your area of interest and why you want to contribute.

  2. 02

    Pick a first task

    Start small: a documentation fix, a test case, a demo scenario, or an analyzer mapping.

  3. 03

    Branch and build

    Make one focused change with tests. Run pytest and ruff locally, the same checks CI runs.

  4. 04

    Open a pull request

    Use the template, link the issue, and expect review. Every change is reviewed before it merges.

git switch -c adapter/flawfinder
# ...make your change, add tests...
pytest && ruff check . && ruff format --check .
git commit -m "Add flawfinder analyzer adapter"
git push -u origin adapter/flawfinder

04Code standards

How astrapatch code is written.

Python 3.11+
Modern syntax: X | None, StrEnum, tomllib.
Zero runtime dependencies
The core installs with the standard library only. Propose any dependency in an issue first.
Ruff
Code passes ruff check and ruff format. Line length 110.
Determinism
Same inputs, same outputs. Sort anything written to disk.
Failure isolation
An adapter that fails reports its error and never hides other results.
Tests
Every behavior change comes with a test.

05First tasks

Good places to start.

  • Fix or clarify documentationStage 01
  • Add a test case that proves a pattern is found, or correctly ignoredStage 02 · 03 · 06
  • Add a scenario to the demo, such as an empty or truncated packetStage 04 · 06
  • Add a SARIF fixture from another analyzer and test the importStage 03 · 05
  • Improve the CWE or severity mapping in an adapterStage 03
Stage numbers refer to the learning roadmap

06Security and conduct

Working safely and respectfully.

Reporting vulnerabilities. Do not open public issues for security problems in astrapatch. Use GitHub's private vulnerability reporting under the repository's Security tab.

Conduct. The project follows the Contributor Covenant 2.1. Be respectful, assume good faith, and keep disagreement on the work.

License. astrapatch is licensed under the Apache License 2.0. Under section 5 of that license, contributions you submit are provided under the same license unless you state otherwise.