From d36588a363b37628ce0b3a0dc7d6cb8a1d257f17 Mon Sep 17 00:00:00 2001 From: Max Stewart Date: Tue, 16 Dec 2025 12:11:03 +0000 Subject: [PATCH] Add maintainer guidance --- .github/CONTRIBUTING.md | 4 ++ .github/MAINTAINERS.md | 132 ++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++- 3 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 .github/MAINTAINERS.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0c3c8b380c..d73f04b636 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,3 +1,7 @@ +> **Are you a maintainer?** +> Please also read `MAINTAINERS.md` for project vision, quality expectations +> and maintainer responsibilities. + # Contributing Guide Contributions are welcome and are greatly appreciated! Every little bit helps. diff --git a/.github/MAINTAINERS.md b/.github/MAINTAINERS.md new file mode 100644 index 0000000000..c9cd799a93 --- /dev/null +++ b/.github/MAINTAINERS.md @@ -0,0 +1,132 @@ +# Maintainers Guide + +This document is for people with maintainer permissions on +XGovFormBuilder/digital-form-builder. + +Maintainers are responsible for: + +- Protecting the long-term vision of the project +- Keeping the designer and runner aligned +- Enforcing quality: tests, style, accessibility, docs +- Being good stewards of the community (see CODE_OF_CONDUCT.md) + +If you’re not a maintainer, see CONTRIBUTING.md instead. + +## Vision and scope + +**Vision** + +XGov Digital Form Builder exists to let anyone quickly design and deploy +high-quality, GOV.UK-style forms. + +We do this via two main pieces: + +- **Designer** – a UI for building forms through a simple, low-code interface +- **Runner** – an app that serves and runs those forms for end users + +**As a maintainer, you agree to:** + +1. **Keep designer and runner in sync** + + - Any change to the form model, components or behaviour that affects one + SHOULD be reflected in the other. + - Prefer changes that improve both designer and runner rather than + introducing “designer-only” or “runner-only” concepts. + - If you must diverge temporarily, open an issue to track re-alignment and + reference it in the PR. + +2. **Stay within scope** + + - We focus on **GOV.UK-style** digital forms and journeys. + - Avoid adding features that: + - conflict with GOV.UK Design System and Service Standard, or + - turn the project into a generic “do everything” app builder. + - When in doubt about scope, open a discussion/ADR rather than merging. + +## Quality expectations + +Maintainers are the last line of defence for quality. Before you merge, you +are responsible for ensuring: + +### Tests + +- New features come with appropriate **unit tests** and, where relevant, + **integration/e2e tests**. +- CI must be green. Do not merge on red or “flaky but probably fine” runs. +- When fixing a bug, add at least one test that fails before the fix + and passes after. + +### Style & consistency + +- Code must follow the project’s eslint/prettier/tsconfig setup. +- Prefer existing patterns over new ones: + - Use established component and model patterns before inventing new abstractions. + - Keep naming consistent with existing code (e.g. same terminology in designer, + runner and docs). + +### Accessibility & UX + +- Changes to UI must consider accessibility: + - Use GOV.UK Design System components and patterns wherever possible. + - Ensure labels, error messages and focus states are correct. +- Try the change in both **designer** and **runner** and sanity-check the + user journey. + +### Documentation + +- Significant behaviour or model changes must be documented: + - Update relevant README/feature docs/ADRs. + - Note breaking changes clearly in the changelog / release notes + (see versioning rules). + +## Maintainer workflow + +### Branching and merging + +- Use pull requests for all changes (no direct commits to `main`). +- Use the existing commit prefixes for SemVer: + - `breaking:` / `major:` + - `feature:` / `minor:` + - `fix:` / `patch:` +- Never bypass review on your own non-trivial PRs: + - At least **one other maintainer** should approve, unless: + - change is trivial (docs/typo) AND + - no behaviour or API changes. + +### Reviews + +When reviewing PRs, maintainers should: + +1. **Check alignment with vision** + + - Does this help people build GOV.UK-style forms more easily? + - Does it keep designer and runner aligned? + +2. **Check quality** + + - Tests added/updated? + - CI green? + - Code follows existing patterns? + +3. **Be constructive** + - Prefer "how can we get this over the line?" to "no". + - Suggest concrete changes when requesting changes. + +### Security & compliance + +- Treat secrets, keys and environment variables with care. +- Do not commit secrets. If a leak happens, rotate and document the incident. +- Follow GOV.UK and general security best practices (input validation, output + encoding, etc.). + +## Architecture decisions + +- Non-trivial changes to architecture, data model or external interfaces + (e.g. how forms are stored/run) SHOULD have an Architecture Decision Record (ADR). +- ADRs should: + - explain the problem, + - list options considered, + - record the decision and rationale. + +Maintainers are responsible for keeping ADRs up to date when behaviour diverges +from what’s written. diff --git a/README.md b/README.md index 50fee06d20..6dc2194635 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,17 @@ # XGov Digital Form Builder +## Project vision + +- Allow anyone to design and deploy GOV.UK-style forms quickly +- Provide a low-code **designer** and a robust **runner** that stay in sync +- Favour standards-compliant, accessible journeys over one-off customisations + ## Support - Join the [community on slack](https://join.slack.com/t/xgov-digital-form-bld/shared_invite/zt-xn5ltztf-3_oBzZaziV4sCpDDOGuP6Q) - Contact [support@cautionyourblast.com](mailto:support@cautionyourblast.com) if you are unable to join Slack in your organisation. -## contributions +## Contributions Issues and pull requests are welcome. Please check [CONTRIBUTING.md](.github/CONTRIBUTING.md) first!