Skip to content
This repository was archived by the owner on Aug 11, 2025. It is now read-only.

Commit 20f7968

Browse files
committed
feat(docs): Adding background document with some user stories
1 parent 27b36d6 commit 20f7968

1 file changed

Lines changed: 42 additions & 0 deletions

File tree

BACKGROUND.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
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

Comments
 (0)