Community

Contributing guide.

The repository contribution guide is rendered here for the framework site.

# Contributing to PED

PED is an open initiative for practitioners who want delivery governance to
become more observable, more evidence-based, and less dependent on approval
queues.

The project benefits most from concrete, testable contributions:

- a new control example from a real kind of codebase
- a better decision-record field or schema constraint
- a clearer adoption path
- a write-up of a control that was not worth keeping
- a practical FAQ entry from a hard governance conversation

## Principles

- Prefer evidence over slogans.
- Keep examples runnable.
- Name ambiguity directly.
- Make deterministic checks machine-readable.
- Do not hide human judgment behind vague approval language.
- Use plain language. This project should be useful to engineers, security
  teams, auditors, product teams, and operations teams.

## Contribution Flow

1. Open an issue or discussion for broad framework changes.
2. For docs or examples, open a pull request directly when the change is clear.
3. Include enough context for reviewers to understand the delivery scenario.
4. Add or update tests when changing examples, schemas, or validators.
5. Keep generated artifacts in sync when updating the whitepaper or decks.

## Local Checks

```sh
npm test
npm run build
opa test examples/terraform
go test ./examples/go/...
python3 -m unittest discover examples/python
```

## Writing Style

PED should not read like vendor copy. Write as if you are explaining the idea
to a capable peer who has limited time and a real queue of approvals waiting.

Good writing:

- states the decision being made
- names the evidence required
- explains when cognition is necessary
- avoids pretending every organization is mature

## Commit Style

Use conventional commits:

- `docs: clarify adoption path`
- `feat(examples): add docs repository control`
- `fix(schema): require control status`
- `ci: validate generated artifacts`