From e4c6a28931f463139b5bc25cb08e8abf215be7c1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 4 Oct 2025 15:58:09 +0000 Subject: [PATCH] Add technical rules for PRs and update teamwork documentation Co-authored-by: louis --- README.md | 3 +++ product/TEAMWORKFLOW.md | 2 ++ product/TECHNICAL_RULES.md | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 37 insertions(+) create mode 100644 product/TECHNICAL_RULES.md diff --git a/README.md b/README.md index ed8ecda..325d9f5 100644 --- a/README.md +++ b/README.md @@ -55,4 +55,7 @@ This starter kit follows Acta's development principles: - [ ] CHANGELOG.md updated - [ ] Lints and builds pass +### Technical Rules +- See `product/TECHNICAL_RULES.md` for engineering rules (e.g., prefer tiny PRs) + Built with ❤️ by Acta, based on the excellent [T3 Turbo](https://github.com/t3-oss/create-t3-turbo) template. diff --git a/product/TEAMWORKFLOW.md b/product/TEAMWORKFLOW.md index 8631eeb..d48333a 100644 --- a/product/TEAMWORKFLOW.md +++ b/product/TEAMWORKFLOW.md @@ -19,6 +19,8 @@ This document outlines how we work internally at Acta in the product teams. This - Always open a PR to `dev` that you squash + merge for a clean commit history. - Release PRs from `dev` to `main` should include comprehensive changelog updates. +See also: `product/TECHNICAL_RULES.md` for guidelines on PR size and structure (prefer tiny PRs). + ## Release process - **Regular releases** - We promote `dev` to `main` every few days (typically 2-3 days). - **Release responsibility** - Any team member can initiate a release by creating a PR from `dev` to `main`. diff --git a/product/TECHNICAL_RULES.md b/product/TECHNICAL_RULES.md new file mode 100644 index 0000000..3311814 --- /dev/null +++ b/product/TECHNICAL_RULES.md @@ -0,0 +1,32 @@ +# Technical Rules + +This document captures engineering practices that keep quality high while maximizing iteration speed. It is a living document. + +## Prefer tiny PRs + +Small, focused pull requests lead to faster reviews, fewer defects, and easier rollbacks. + +### Why this matters +- Faster review cycles and higher reviewer throughput +- Lower cognitive load and clearer intent per change +- Reduced merge conflicts and safer deploys +- Easier to bisect and revert when issues arise + +### Guidelines +- Aim for PRs that can be reviewed in ≤ 10 minutes +- Scope each PR to a single change or concern +- Do not mix refactors with behavior changes; land preparatory refactors separately +- Split work if it touches many files or requires substantial diff volume +- Keep diffs focused; avoid drive-by changes unrelated to the scope +- Provide crisp context in the description (what/why, screenshots if UI, migration notes) +- Include tests for changed behavior (unit/integration/e2e as appropriate) +- Open Draft PRs early to gather feedback and surface risks +- If a large PR is unavoidable: outline the plan, call out risk areas, and list follow-ups + +### Reviewer expectations +- Prioritize small PRs for quick turnaround +- If a PR feels too large, request a split into smaller, self-contained changes + +### Related +- See `product/TEAMWORKFLOW.md` for the Definition of Done and release process +