Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# Contributing to Atelier
|
||
|
||
Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.
|
||
|
||
## What We Accept
|
||
|
||
- **New domain first-principles** — if a domain is missing (e.g., `domains/ai-ml/`), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in `matrix/principles-matrix.md`.
|
||
- **New domain derived docs** — topic docs under an existing domain (e.g., `domains/api/webhooks.md`), deriving from the domain's first-principles.
|
||
- **New language application docs** — `languages/<lang>.md` showing how domain principles apply in a specific language.
|
||
- **New examples** — `examples/good/*` (with principle citations) or `examples/bad/*` (with violation citations).
|
||
- **Corrections** — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
|
||
- **Improvements to the matrix** — if a derivation is missing or wrong, propose the fix with the rationale.
|
||
|
||
## What We Do Not Accept
|
||
|
||
- **Style rules** — Atelier is principles, not style. Use a linter for style.
|
||
- **Tooling** — linters, analyzers, or enforcement code. Atelier is markdown.
|
||
- **Unlisted docs** — every document must be in `MANIFEST.md`. An unlisted doc is not part of the framework.
|
||
- **Principles without derivation** — a domain principle that does not trace to a core principle is orphaned and will be rejected.
|
||
|
||
## How to Contribute
|
||
|
||
### 1. Read the relevant docs first
|
||
- `core/first-principles.md` — the eight axioms.
|
||
- `core/conflict-resolution.md` — how conflicts are resolved.
|
||
- The domain(s) you are contributing to.
|
||
- `matrix/principles-matrix.md` — to see existing derivations.
|
||
|
||
### 2. Follow the document structure
|
||
See `domains/documentation/doc-templates.md` for the canonical structure. Every first-principles doc has:
|
||
- Manifesto
|
||
- The Principles (P1–P10, named, defined, with "what violates it")
|
||
- Conflict Resolution
|
||
- What Violates These Principles (table)
|
||
- Relationship to Core
|
||
|
||
### 3. Update the matrix
|
||
If you add or change a principle, update `matrix/principles-matrix.md` with the derivation. A PR with a new principle but no matrix row is incomplete.
|
||
|
||
### 4. Update the manifest
|
||
If you add a new document, add it to `MANIFEST.md` in the correct section. An unlisted document is not part of the framework.
|
||
|
||
### 5. Add examples
|
||
If you add a principle, add at least one good example and one bad example in `examples/`. Examples are mandatory (Documentation P3).
|
||
|
||
### 6. Write a clear PR description
|
||
- What principle or document you are adding/changing.
|
||
- Why (the rationale, not just the what — Documentation P8 Why Over What).
|
||
- Which core principle(s) it derives from.
|
||
- What conflicts it might introduce (if any).
|
||
|
||
## Review Criteria
|
||
|
||
Reviewers will check (see `review/peer-review-checklist.md`):
|
||
- Does the new principle trace to a core principle?
|
||
- Is the matrix updated?
|
||
- Is the manifest updated?
|
||
- Are there examples?
|
||
- Does the structure follow the template?
|
||
- Does it conflict with existing principles? If so, is the conflict resolvable per `core/conflict-resolution.md`?
|
||
|
||
## Versioning
|
||
|
||
- A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
|
||
- A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
|
||
- A change to `core/first-principles.md` (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
|
||
- See `CHANGELOG.md` for the version history.
|
||
|
||
## License
|
||
|
||
By contributing, you agree that your contributions are licensed under the MIT license (see `LICENSE`). |