docs: initialize engineering starter kit

2026-06-28 09:40:40 +02:00
commit ed8efda692
23 changed files with 3131 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Branching Strategy
+
+This document defines the default Git branching strategy.
+
+For delivery workflow, see [workflow.md](workflow.md).
+For pull request expectations, see [CONVENTIONS.md](CONVENTIONS.md#pull-requests).
+
+## Default Model
+
+Use a simple trunk-based model unless the project has a clear reason to add
+long-lived release branches.
+
+```mermaid
+gitGraph
+    commit id: "main"
+    branch feature
+    checkout feature
+    commit id: "work"
+    commit id: "validate"
+    checkout main
+    merge feature
+    commit id: "release"
+```
+
+## Branch Types
+
+| Type | Pattern | Purpose |
+| --- | --- | --- |
+| Feature | `feature/{{short-description}}` | New user-facing or system capability. |
+| Bug fix | `fix/{{short-description}}` | Defect correction. |
+| Refactor | `refactor/{{short-description}}` | Behavior-preserving structural improvement. |
+| Documentation | `docs/{{short-description}}` | Documentation-only changes. |
+| Chore | `chore/{{short-description}}` | Maintenance work with no product behavior change. |
+| Release | `release/{{version}}` | Optional stabilization branch for release trains. |
+| Hotfix | `hotfix/{{short-description}}` | Urgent production correction. |
+
+## Main Branch
+
+The `main` branch should remain deployable or releasable according to the
+project's release model.
+
+Minimum expectations:
+
+- Required checks pass.
+- Changes are reviewed when the project requires review.
+- Risky migrations and config changes are documented.
+- Direct pushes are limited to repository maintainers or automation.
+
+## Feature Branches
+
+Feature branches should be short lived.
+
+- Keep scope focused.
+- Rebase or merge from `main` according to project policy.
+- Delete branches after merge.
+- Avoid stacking unrelated changes.
+
+## Release Branches
+
+Use release branches only when needed for stabilization, compliance, or release
+train coordination.
+
+Release branches should receive:
+
+- Critical fixes.
+- Release documentation.
+- Version updates.
+- No unrelated refactors.
+
+## Hotfixes
+
+Hotfixes should prioritize production restoration.
+
+Process:
+
+1. Create a hotfix branch from the deployed commit or release branch.
+2. Apply the smallest safe fix.
+3. Validate the specific failure path.
+4. Release.
+5. Merge the hotfix back into `main`.
+6. Add follow-up work for broader cleanup if needed.
+
+## Commit Messages
+
+Use meaningful commit messages that explain the outcome.
+
+Recommended format:
+
+```text
+{{type}}: {{short imperative summary}}
+
+{{optional context, rationale, or validation notes}}
+```
+
+Examples:
+
+- `docs: add starter architecture guide`
+- `fix: prevent duplicate invoice submission`
+- `refactor: isolate payment gateway retries`
+
+## Merge Policy
+
+Choose one policy per project:
+
+| Policy | Best When |
+| --- | --- |
+| Squash merge | Small teams want clean history and one commit per PR. |
+| Merge commit | Teams want to preserve branch context. |
+| Rebase merge | Teams want linear history with individual commits. |
+
+Record the selected policy in [PROJECT.md](PROJECT.md) or this file.