Contributing
LOTA development happens on the lota-next integration branch. main
carries only stable released code. Open pull requests against lota-next;
the branch model is documented in branching.
Security first
Changes must preserve the production security contract. Do not add development shortcuts that weaken TPM enrollment, verifier policy, BPF LSM enforcement, SELinux confinement, release signing, or reproducible builds.
If a change affects an external contract, update the matching documentation in the same commit. Examples include CLI flags, policy syntax, IPC wire formats, systemd units, SELinux labels, SDK APIs, and verifier configuration.
Developer Certificate of Origin
Every commit must carry a DCO sign-off:
Signed-off-by: Name <email@example.com>
Use git commit -s or add the line manually. The sign-off certifies that
the contribution can be submitted under the project's licenses.
Commit style
Use one logical change per commit. A commit should build and test on its own. Keep unrelated refactors separate from behavior changes.
Commit subjects use a bare prefix:
agent: reject stale AIK metadata
verify: bind quote nonce to token epoch
docs/verifier: describe monitoring API authentication
ci: shard Go fuzz targets
Do not use Conventional Commit parentheses such as fix(agent):.
Commit bodies for ALL changes should state:
Problem: ...
Solution: ...
Signed-off-by: Name <email@example.com>
Code style
C and BPF code follow the repository .clang-format.
Run clang-format -i on modified C and header files before committing.
Go code must be formatted with gofmt.
Comments should be terse and factual. State the contract, failure mode, or relevant specification. Avoid narrative comments.
Local validation
For normal changes, run:
env GOCACHE=/tmp/lota-gocache make BUILD_DIR=/tmp/lota-build all
env GOCACHE=/tmp/lota-gocache make BUILD_DIR=/tmp/lota-build test-unit
Broaden validation when the change touches a wider surface:
BPF LSM or kernel hooks: validate in a guest with the production BPF object attached.
TPM paths: validate with
swtpm- hardware TPM validation is required before release claims that depend on hardware behavior.Untrusted parsers: add or update fuzz seeds and run the matching fuzz target.
Release artifacts: run
make reproducible-build.SELinux policy: rebuild the module and inspect the resulting AVC behavior on an enforcing system.
The full testing policy is in development/index.
Reporting issues
Open new issue and pick a template.
Bug is for non-security defects; Enhancement is for a proposed change
or capability. Both live in .github/ISSUE_TEMPLATE and keep the report terse
and reproducible.
Suspected vulnerability never goes in a public issue. Use the Private Security Reporting link in the new-issue chooser, which opens a private GitHub advisory; the encrypted-email fallback and GPG fingerprint are in the security policy.
Pull request expectations
Opening a pull request pre-populates .github/PULL_REQUEST_TEMPLATE.md.
Keep its sections (Problem, Solution, per-area detail, Docs, Tests, Security
boundary); they mirror the required commit-body structure.
A pull request should include:
focused change set,
tests or a clear reason why runtime validation needs operator hardware (if it does),
documentation updates for changed behavior,
no generated build artifacts,
no private operator files, local logs, TPM state, or credentials.
Tagging releases and promoting lota-next to main are maintainer
actions.