From 995e039b88e2efa4094789b4938dc9c4dfaff9b1 Mon Sep 17 00:00:00 2001 From: escapedcat Date: Tue, 16 Jun 2026 18:55:52 +0200 Subject: [PATCH] docs: add TDD commit flow and review expectations for contributors - CONTRIBUTING: document the test-first then implementation commit flow (short example + link to a TDD explainer), reconcile it with the prior "squash your commits" line, and add a "Working with maintainers" note on responding to review feedback. - PR template: checklist items for verifying doc examples and following the TDD commit flow. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/CONTRIBUTING.md | 25 ++++++++++++++++++++++++- .github/PULL_REQUEST_TEMPLATE.md | 2 ++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d1adbbac69..86c8f7624d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -30,7 +30,7 @@ Please consider these guidelines when filing a pull request: - Follow the [Coding Rules](#coding-rules) - Follow the [Commit Rules](#commit-rules) - Make sure you rebased the current master branch when filing the pull request -- Squash your commits when filing the pull request +- Keep a clear commit history: squash incidental/WIP commits, but for features and bug fixes follow [Test-driven development](#test-driven-development) — a failing-test commit, then the implementation - Provide a short title with a maximum of 100 characters - Provide a more detailed description containing _ What you want to achieve @@ -38,6 +38,10 @@ Please consider these guidelines when filing a pull request: _ What you added _ What you removed +### Working with maintainers + +A pull request is driven by its author. When you receive review feedback — whether from a maintainer or an automated reviewer — please either address it or reply explaining why you'd skip it, so the PR can keep moving. If anything is unclear, just ask; we're happy to help. + ### Coding Rules To keep the code base of commitlint neat and tidy the following rules apply to every change @@ -97,6 +101,25 @@ pnpm build pnpm test ``` +### Test-driven development + +For features and bug fixes we follow [test-driven development](https://martinfowler.com/bliki/TestDrivenDevelopment.html) ("red, green, refactor"): write a test that fails because the behavior doesn't exist yet, then write the code that makes it pass. + +Please mirror this in your pull request with two commits: + +1. **Tests first** — add tests for the new behavior. On their own they must fail (CI red), which proves they actually exercise the change. +2. **Implementation** — add the code that makes them pass (CI green). + +Make sure the test commit fails for the _right reason_ — a failing assertion, not a build error — and that each test would pass only _with_ your change. A test that passes without the implementation isn't testing it. + +```sh +# commit 1 — failing tests (CI red) +git commit -m "test: cover " + +# commit 2 — implementation (CI green) +git commit -m "feat(): " +``` + ### Documentation updates Documentation uses `vitepress`. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3f26ef9948..82338e9c21 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -41,5 +41,7 @@ echo "your commit message here" | commitlint # fails/passes - [ ] My change requires a change to the documentation. - [ ] I have updated the documentation accordingly. +- [ ] I have verified that any documentation examples I added/changed actually work. - [ ] I have added tests to cover my changes. - [ ] All new and existing tests passed. +- [ ] For a feature/bug fix, my commits follow the [test-driven flow](https://github.com/conventional-changelog/commitlint/blob/master/.github/CONTRIBUTING.md#test-driven-development): a failing-test commit, then the implementation.