An open source design system that's fully customizable and agent ready
TypeScript
docs: add intent-specific pull request templates (#6257)
Cindy Zhang6c5304cd590a
diff --git a/.github/PULL_REQUEST_TEMPLATE/bug-fix.md b/.github/PULL_REQUEST_TEMPLATE/bug-fix.mdnew file mode 100644index 0000000000..bb06f03134--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/bug-fix.md@@ -0,0 +1,31 @@+<!-- Use this template only when the primary intent is to restore broken behavior. -->++## User impact++<!-- Who encounters the defect, in what state, and what fails? -->++## Expected behavior and authority++<!-- Link the current contract, standard, documented promise, or regression history that defines the expected outcome. -->++## Smallest restoration++<!-- Explain the narrow fix. Remove or split new API, visual affordances, layout changes, cleanup, and other tagalongs. -->++## Evidence++- Reproduction before the change:+- Result after the change:+- Representative unchanged path:+- Regression test or other mutation-sensitive proof:++## Scope++- [ ] One defect is restored.+- [ ] Separable contradictory or unsettled tagalongs were removed or split.+- [ ] No new public API, visual representation, default, or interaction model is hidden under the bug-fix label.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Commands and real-browser states where behavior depends on layout, pixels, focus, scrolling, hit testing, or input modality. -->diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.mdnew file mode 100644index 0000000000..a9d48f326a--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md@@ -0,0 +1,27 @@+<!-- Use this template only when documentation is the primary intent. -->++## Reader impact++<!-- Who is misled, blocked, or missing guidance, and what can they do after this change? -->++## Source of truth++<!-- Link the code, current contract, generated schema, or other authority the documentation must match. -->++## Correction++<!-- State the incorrect or missing guidance and the exact corrected meaning. -->++## Evidence++<!-- Rendered page, generated output, link/check result, or example validation. -->++## Scope++- [ ] This PR changes documentation only, or names every necessary generated artifact.+- [ ] Runtime, API, visual, and policy changes were removed or split.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Documentation checks, generated-file verification, link checks, or rendered review. -->diff --git a/.github/PULL_REQUEST_TEMPLATE/maintenance.md b/.github/PULL_REQUEST_TEMPLATE/maintenance.mdnew file mode 100644index 0000000000..aaff259181--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/maintenance.md@@ -0,0 +1,29 @@+<!-- Use this template for CI, tests, tooling, refactors, dependencies, or repository maintenance with no intended product behavior change. -->++## Maintainer impact++<!-- What operational or engineering problem occurs, for whom, and under what conditions? -->++## Intended invariant++<!-- Link current tooling/architecture authority or state the maintained behavior that must remain unchanged. -->++## Change++<!-- Explain the smallest mechanism change and why it belongs in maintenance rather than product behavior. -->++## Evidence++- Failure before the change:+- Success after the change:+- Product/runtime behavior verified unchanged:++## Scope++- [ ] No intended public API, product behavior, visual direction, or policy change.+- [ ] Product changes discovered during the work were removed or split.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Commands, failure injection, CI dry run, generated output, or performance evidence. -->diff --git a/.github/PULL_REQUEST_TEMPLATE/new-feature.md b/.github/PULL_REQUEST_TEMPLATE/new-feature.mdnew file mode 100644index 0000000000..95760f3bb7--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/new-feature.md@@ -0,0 +1,32 @@+<!-- Use this template only when adding a new user-facing capability is the primary intent. -->++## User need++<!-- Who needs this capability, in what state, and why existing composition does not solve it? -->++## Current specification++<!-- Link the current owner and exact decision admitting the capability and any public API. -->++## Public delta++<!-- List observable behavior, API/types/defaults, compatibility, theming, and accessibility changes. Include representative consumer syntax when API changes. -->++## Design and alternatives++<!-- Explain the chosen model and the meaningful alternatives rejected by the specification. -->++## Evidence++<!-- Prove default, configured, composed, edge, accessibility, visual, and unchanged legacy paths as applicable. -->++## Scope++- [ ] One capability is added.+- [ ] Unrelated fixes, cleanup, and policy changes were removed or split.+- [ ] Consumer docs, focused tests, and migration evidence ship with the feature.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Commands and real-browser/state matrix. -->diff --git a/.github/PULL_REQUEST_TEMPLATE/other.md b/.github/PULL_REQUEST_TEMPLATE/other.mdnew file mode 100644index 0000000000..d25729c90d--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/other.md@@ -0,0 +1,27 @@+<!-- Use this only when no more specific template fits. Explain why. -->++## Primary intent++<!-- Why does this PR exist, and why do the other templates not fit? -->++## User or maintainer impact++<!-- Who is affected, in what state, and what changes? -->++## Authority++<!-- Link current requirements or the owner-approved decision. -->++## Change and evidence++<!-- Describe the smallest change and the reproducible proof. -->++## Scope++- [ ] This PR has one primary intent.+- [ ] Independently removable deltas were removed or split.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Commands and relevant browser/state evidence. -->diff --git a/.github/PULL_REQUEST_TEMPLATE/specification.md b/.github/PULL_REQUEST_TEMPLATE/specification.mdnew file mode 100644index 0000000000..669ac0ddac--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/specification.md@@ -0,0 +1,38 @@+<!-- Use this template only when recording a durable decision is the primary intent. Do not include implementation. -->++## Exact decision needed++<!-- State the smallest unresolved public behavior, API, ownership, compatibility, theme, or design claim. -->++## Existing authority searched++<!-- Name current records, affected paths/exports, semantic terms, and overlapping open PRs inspected. Explain why no existing claim settles this decision. -->++## Decision++<!-- State the approved requirement, conditions, defaults, exceptions, compatibility, and owner. -->++## Rejected alternatives++<!-- Record only consequential alternatives likely to recur. -->++## Claim scope and non-goals++<!-- A current record governs only these explicit claims. Leave adjacent behavior uncontracted instead of filling it for completeness. -->++## Evidence and implementation relationship++<!-- Evidence supporting the decision; linked implementation PR if one exists. The specification must remain valid without it. -->++## Scope++- [ ] This PR contains specification records only.+- [ ] It records one intentional durable decision, not a review transcript or rescue for a separable tagalong.+- [ ] Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.+- [ ] Public text and artifacts contain no internal Meta context.++## Validation++- `pnpm check:knowledge`+- Prettier+- `git diff --check`diff --git a/.github/PULL_REQUEST_TEMPLATE/visual-update.md b/.github/PULL_REQUEST_TEMPLATE/visual-update.mdnew file mode 100644index 0000000000..50c9be21ed--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE/visual-update.md@@ -0,0 +1,31 @@+<!-- Use this template only when appearance is the primary intent. -->++## User impact++<!-- Who is affected, in what visual state, and what becomes clearer, more consistent, or more usable? -->++## Visual authority++Choose one and link it:++- [ ] Correction already settled by current component, family, design, theme, or objective accessibility authority.+- [ ] New visual direction settled by an owner-approved current specification.++## Before and after++<!-- Embed matched real-browser screenshots. Keep viewport, content, theme, and state identical except for the change. -->++## State matrix++<!-- Cover relevant themes, light/dark modes, viewport/container sizes, LTR/RTL, input states, and the unchanged legacy/default path. -->++## Scope++- [ ] Appearance is the primary intent.+- [ ] Behavior, API, interaction model, and unrelated layout changes were removed or split.+- [ ] The evidence shows the changed pixels actively running, not only source or computed styles.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Visual regression, focused tests, and browser checks. -->diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 0000000000..511d251368--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,35 @@+<!--+Choose the template matching this PR's primary intent from+.github/PULL_REQUEST_TEMPLATE/. See docs/contributing/pull-requests.md.+Keep one primary intent; remove or split independently reviewable tagalongs.+-->++## Primary intent++<!-- Bug fix, visual update, new feature, documentation, specification, maintenance, or other. Why does this PR exist? -->++## User or maintainer impact++<!-- Who is affected, in what state, and what improves? -->++## Authority++<!-- Link current requirements or the owner-approved decision. Say "none found" only after searching. -->++## Change++<!-- Describe the smallest change that satisfies the primary intent. -->++## Evidence++<!-- Show the affected before/after state and representative unchanged paths. Use real-browser pixels for visual claims. -->++## Scope++- [ ] This PR has one primary intent.+- [ ] Independently removable API, visual, layout, behavior, cleanup, and policy changes were removed or split.+- [ ] Public text and artifacts contain no internal Meta context.++## Testing++<!-- Commands, browser/state matrix, generated output, or other reproducible checks. -->diff --git a/AGENTS.md b/AGENTS.mdindex b38389c495..5887263203 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -17,6 +17,9 @@ nested `AGENTS.md`.`packages/cli/assets/docs/`.- Contributors: read `CONTRIBUTING.md` and the relevant guidance linked from`docs/README.md`.+- Pull requests: choose one primary intent and use its template under+ `.github/PULL_REQUEST_TEMPLATE/`; read `docs/contributing/pull-requests.md`+ before opening or reviewing a mixed change.- Component work: read the component's `{Name}.spec.md` when one exists, thenany `module:*` records it lists for the public module being changed, followed byconsumer docs, tests, and implementation.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a053b7960f..aa3079e961 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -4,6 +4,7 @@ For the full contribution process — what we accept, how to propose new componeKey pages:+- **[Pull request intents](docs/contributing/pull-requests.md)** — choose one primary intent, its evidence bar, and the matching PR template- **[API conventions guide](docs/contributing/api-conventions.md)** — practical naming, composition, styling, proposal, and review guidance linked to current owner records- **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)** — the design-side bar: tokens, spacing, radius, elevation, type, color, motion, and state representations- **[Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** — the 9-phase process for new componentsdiff --git a/docs/contributing/README.md b/docs/contributing/README.mdindex 984a26cd35..811ea24e16 100644--- a/docs/contributing/README.md+++ b/docs/contributing/README.md@@ -4,6 +4,8 @@ These guides turn current Astryx owner records into practical contribution stepsThey do not create policy or replace architecture, specifications, familycontracts, or component contracts.+- [Pull request intents](pull-requests.md): choose one primary intent, use the+ matching template, and supply the right evidence without absorbing tagalongs.- [API conventions](api-conventions.md): shape, propose, implement, and review apublic component API.- [CLI conventions](cli-conventions.md): propose, implement, and review a changediff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.mdnew file mode 100644index 0000000000..4848c8610d--- /dev/null+++ b/docs/contributing/pull-requests.md@@ -0,0 +1,46 @@+# Pull requests: one primary intent++A pull request should make one reviewable change for one reason. Choose the template that matches its primary intent; supporting tests and docs belong with that intent, but unrelated API, visual, layout, behavior, or policy changes do not.++GitHub uses the default template automatically. To choose another, add `?template=<file>.md` to the new-pull-request URL, or copy the matching file from `.github/PULL_REQUEST_TEMPLATE/` into the description.++| Primary intent | Template | Minimum evidence |+| ---------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |+| Restore broken behavior | `bug-fix.md` | reproduction, expected authority, before/after result, unchanged representative path |+| Correct or intentionally change appearance | `visual-update.md` | current visual authority or owner decision, real-browser before/after pixels, relevant state matrix |+| Add a capability | `new-feature.md` | user need, current specification, complete public delta, behavior and compatibility evidence |+| Correct contributor or consumer documentation | `documentation.md` | reader impact, source of truth, rendered or generated result |+| Record a durable decision | `specification.md` | exact unresolved claim, existing authority searched, decision, rejected alternatives, explicit non-goals |+| Change tooling, tests, CI, or repository maintenance | `maintenance.md` | operational problem, failure proof, success proof, unchanged product behavior |+| Anything else | `other.md` | primary intent, user or maintainer impact, authority, evidence |++## Keep the intent atomic++Before requesting review, partition every observable delta:++- **Primary:** the reason this pull request exists.+- **Supporting:** evidence or documentation required to make the primary change complete.+- **Tagalong:** independently removable behavior, visual, API, layout, policy, or cleanup.++Remove or split tagalongs. A bug fix does not become a feature because a nearby affordance could also improve. A feature does not absorb unrelated cleanup because the same file is open.++## Use specifications last, not first++Review should produce the smallest ideal change that can land:++1. Apply current component, module, family, design, theme, architecture, and system authority to each delta.+2. If a delta violates current authority, conform or remove it. Do not propose changing the specification merely to rescue the implementation.+3. If a delta is unsettled but separable, remove or split it and keep reviewing the primary intent.+4. Propose a specification only for a surviving, intentional durable decision the team wants to pursue.++A current record governs only its explicit claims inside its ownership boundary. It does not imply that the whole named component or module is fully specified.++## Visual corrections++A visual change does not automatically need a new specification. It may proceed as a correction when current component, family, design, theme, or objective accessibility authority already settles the exact outcome. Show that authority and verify the affected state with real-browser pixels, plus representative unchanged states.++A new visual representation, subjective direction, or interaction model remains a design decision. Put that decision in its own specification or owner-reviewed visual update instead of attaching it to a bug fix.++## Public repository boundary++Descriptions, screenshots, commits, tests, and specification records are public. Do not include internal links, identifiers, hostnames, tools, or operational context.diff --git a/docs/templates/knowledge/module-spec.md b/docs/templates/knowledge/module-spec.mdindex 09dd976d5e..7278a72d4d 100644--- a/docs/templates/knowledge/module-spec.md+++ b/docs/templates/knowledge/module-spec.md@@ -19,7 +19,7 @@ references: [architecture:<surface>, design:<surface>, spec:AST-000/DEC-0]## Intent-<!-- Why this public semantic module exists and the component-local job it owns. Private implementation helpers do not need records. Consumer usage belongs in the module's .doc.mjs. -->+<!-- Why this public semantic module exists and the component-local job it owns. Private implementation helpers do not need records. Consumer usage belongs in the module's .doc.mjs. A current module record may contract one named semantic slice; state that boundary and leave adjacent behavior uncontracted rather than filling it for completeness. -->## Compatibility and migration