|
| 1 | +## Background & Philosophy of `check-commit` |
| 2 | + |
| 3 | +`check-commit` is more than just a pre-commit hook; it's a tool designed to support a specific way of working. |
| 4 | +This document explains the philosophy behind its creation and the problems it aims to solve. |
| 5 | + |
| 6 | +### Background: Moving beyond the internal PR model |
| 7 | + |
| 8 | +The Pull Request (PR) is a brilliant invention for managing contributions from untrusted sources in open-source projects. It provides a necessary quality gate to protect the integrity of a codebase. |
| 9 | + |
| 10 | +However, this model has been widely adopted for internal development within trusted teams, where it can become a form of process waste. As outlined in the principles of Trunk-Based Development (TBD), forcing team members through a formal PR process is like making your family go through airport security to enter your home. |
| 11 | +It’s a costly solution to a different problem. |
| 12 | + |
| 13 | +Formal PRs introduce mandatory delays and context switching, disrupting the flow that TBD and Continuous Integration (CI) aim to create. A developer finishes their work, creates a PR, and then waits, breaking their concentration to start another task. The `check-commit` tool was born from this observation: How can we get the quality benefits of a review without the friction of a formal PR process? |
| 14 | + |
| 15 | +### Philosophy: A TBD-Native quality gate |
| 16 | + |
| 17 | +The goal of `check-commit` is to be a lightweight, developer-centric quality gate that aligns with the principles of TBD and Continuous Integration. |
| 18 | + |
| 19 | +It achieves this by shifting the quality check "left," moving it from a slow, asynchronous review process to an immediate, synchronous step right at the moment of commit. |
| 20 | + |
| 21 | +* **It's a conversation, not a gatekeeper:** The interactive checklist is a conversation the developer has with the team's shared standards. It's a quick "Did you remember to...?" nudge, not a formal approval process. |
| 22 | + |
| 23 | +* **It lives with the code:** By defining the checklist in a version-controlled `.dod.yml` file, the team's Definition of Done becomes a living artifact that evolves with the codebase, not a forgotten page in Confluence. |
| 24 | + |
| 25 | +* **It Prioritises flow:** The entire process is designed to be completed in seconds, directly in the terminal. It provides immediate feedback without the context switch of navigating a UI, waiting for CI, or pinging teammates for a review. |
| 26 | + |
| 27 | +### User Stories |
| 28 | + |
| 29 | +Here are a few examples of how `check-commit` supports the team's workflow: |
| 30 | + |
| 31 | +**As a Developer, I want to commit my work to `main` with confidence, so that I don't have to worry about forgetting a key quality step.** |
| 32 | + |
| 33 | +* _Scenario:_ I've just finished a small bug fix. I run `tbdflow commit` (which will use `check-commit` internally). An interactive checklist appears, reminding me to run the unit tests and update the code comments. I confirm I've done so and my code is committed, secure in the knowledge that I've followed our team's standards. |
| 34 | + |
| 35 | +**As a Tech Lead, I want to ensure our team consistently follows our Definition of Done, so that we can maintain a high-quality, stable main branch.** |
| 36 | + |
| 37 | +* _Scenario:_ Our team agrees to add a new security check to our DoD. I update the `.dod.yml` file and commit it. Now, every developer on the team will automatically see the new item on their pre-commit checklist, ensuring the new standard is adopted immediately and consistently. |
| 38 | + |
| 39 | +**As a New Team Member, I want a simple way to learn and follow the team's quality standards, so that I can contribute high-quality code from day one.** |
| 40 | + |
| 41 | +* _Scenario:_ It's my first week on the team. I'm not yet familiar with all the team's NFRs or documentation standards. The `check-commit` tool guides me through the checklist on my very first commit, providing a safety net and an interactive learning tool that helps me get up to speed quickly. |
| 42 | + |
0 commit comments