Community

Where to ask questions, file issues, report vulnerabilities, and contribute. Capa is a personal project but an open one; the channels below are real and monitored.

Channels

GitHub Discussions

Open-ended questions, design conversations, "how do I ...?" help. Use this when you are not sure if your message is a bug, a feature request, or a question; threads here are public and indexed.

Issues

Concrete bug reports and feature proposals. Two YAML forms (bug, feature) collect the fields most likely to be needed; blank issues are turned off so reports never come in half-empty.

Security advisories (private)

For a way to bypass the capability discipline, escape attenuation, or otherwise break Capa's security properties. GitHub's private advisory channel; only repository maintainers see the report. Full policy.

Pull requests

Small fixes can come straight as a PR. Larger changes deserve an issue first to align on scope and direction. The CONTRIBUTING guide covers dev setup, the compiler architecture, and what kinds of contributions help most.

Contributing in one screen

The full CONTRIBUTING.md is the canonical reference. The short version:

  1. Clone and install. git clone https://github.com/nelsonduarte/capa && cd capa && pip install -e .
  2. Run the tests. python -m unittest discover tests (about 15 seconds, 536 tests).
  3. Open an issue first for anything more than a small fix. Avoids the worst kind of pull request: good work that cannot be accepted because the direction is wrong for the project.
  4. One concern per PR. A PR that fixes a bug and adds a feature is two PRs.
  5. Commit messages: imperative, short title (≤ 70 chars), optional wrapped body. Look at git log for examples.

The compiler structure, the kinds of contributions that help most, and the kinds that do not currently fit are all in CONTRIBUTING. Read it before opening a non-trivial PR.

What helps, what does not

Help wanted

  • Bugs in the analyzer: a .capa program that should compile and does not, or vice versa
  • Test coverage in tests/test_analyzer.py, especially around capabilities and consume
  • Documentation fixes: the white paper, EBNF, and tour should match the implementation
  • New examples/: realistic miniatures (a small parser, a small networking client) more than synthetic demonstrations
  • Tooling on the roadmap: language server, formatter, capa init

Not currently a fit

  • Large refactors of analyzer or transpiler without a prior design discussion
  • New built-in capabilities (the seven are deliberate)
  • Major runtime dependencies (the compiler has zero runtime deps outside stdlib)
  • Macros, custom syntax extensions, async/await machinery: explicitly out of scope for v1
  • LLVM backend or self-hosting: far-future, not for v1

Code of conduct

Participation in this project is governed by the Contributor Covenant 2.1, adopted by reference. The maintainer contact for reports is [email protected] (subject line [capa conduct]); reports are handled confidentially and acknowledged within seven days. The full text of the adoption notice is in CODE_OF_CONDUCT.md.

Show up

Capa is at a stage where a thoughtful issue, a small fix, or a use case from the field has a real effect on direction. Drop in.

Open a discussion File an issue Read the contributing guide