Skip to content

Commit 6714693

Browse files
gracefullightsisyphus-dev-ai
gracefullight
and
sisyphus-dev-ai
committed
docs(.agent/rules): create i18n and git branching strategy guides
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
1 parent 54b2e33 commit 6714693

2 files changed

Lines changed: 517 additions & 0 deletions

File tree

‎.agent/rules/branching-strategy.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
---
2+
trigger: model_decision
3+
description: when working with git, branches, or commits
4+
---
5+
6+
# Git Branching Strategy
7+
8+
## Overview
9+
GitFlow-inspired branching strategy for this project. Solo development omits the `develop` branch.
10+
11+
## Branch Types
12+
13+
| Branch | Purpose | Optional |
14+
|--------|---------|----------|
15+
| `main` | Production codebase | No |
16+
| `develop` | Integration for team development | Yes (solo: skip) |
17+
| `feature/*` | New features | No |
18+
| `fix/*` | Bug fixes | No |
19+
| `hotfix/*` | Urgent production fixes | No |
20+
21+
## Branch Naming Rules
22+
23+
- Features: `feature/<descriptive-name>`
24+
- Examples: `feature/user-authentication`, `feature/dark-mode`
25+
26+
- Fixes: `fix/<descriptive-name>`
27+
- Examples: `fix/login-error`, `fix/memory-leak`
28+
29+
## Workflow
30+
31+
### Creating Feature Branch
32+
```bash
33+
# From main (solo or team)
34+
git checkout main
35+
git pull origin main
36+
git checkout -b feature/your-feature-name
37+
38+
# OR from develop (team only)
39+
git checkout develop
40+
git pull origin develop
41+
git checkout -b feature/your-feature-name
42+
```
43+
44+
### Creating Hotfix Branch
45+
46+
```bash
47+
# Always from main (production)
48+
git checkout main
49+
git pull origin main
50+
git checkout -b hotfix/urgent-fix-description
51+
```
52+
53+
### Merging Hotfix
54+
55+
```bash
56+
# 1. Merge to main and tag release
57+
git checkout main
58+
git merge hotfix/urgent-fix-description
59+
git tag -a v1.0.2 -m "Hotfix version 1.0.2"
60+
git push origin v1.0.2
61+
62+
# 2. Back-merge to develop (if using team workflow)
63+
git checkout develop
64+
git merge hotfix/urgent-fix-description
65+
66+
# 3. Delete hotfix branch
67+
git branch -d hotfix/urgent-fix-description
68+
```
69+
70+
### Creating Fix Branch
71+
```bash
72+
# From main (solo or team)
73+
git checkout main
74+
git pull origin main
75+
git checkout -b fix/your-bug-fix
76+
77+
# OR from develop (team only)
78+
git checkout develop
79+
git pull origin develop
80+
git checkout -b fix/your-bug-fix
81+
```
82+
83+
### Merging
84+
```bash
85+
# 1. Update your branch
86+
git pull origin main # or develop
87+
88+
# 2. Run tests and linting
89+
npm test
90+
91+
# 3. Merge to main (solo) or develop (team)
92+
git checkout main # or develop
93+
git merge feature/your-feature-name
94+
95+
# 4. Delete feature branch
96+
git branch -d feature/your-feature-name
97+
```
98+
99+
## Visual Reference
100+
101+
### Solo Development
102+
```mermaid
103+
gitGraph
104+
commit
105+
commit id: "Initial"
106+
branch feature/new-feature
107+
checkout feature/new-feature
108+
commit
109+
commit
110+
checkout main
111+
merge feature/new-feature
112+
branch fix/critical-bug
113+
checkout fix/critical-bug
114+
commit
115+
checkout main
116+
merge fix/critical-bug
117+
commit id: "v1.0.0"
118+
commit id: "v1.0.1"
119+
branch hotfix/urgent-fix
120+
checkout hotfix/urgent-fix
121+
commit
122+
checkout main
123+
merge hotfix/urgent-fix tag: "v1.0.2"
124+
```
125+
126+
### Team Development
127+
```mermaid
128+
gitGraph
129+
commit
130+
commit id: "Initial"
131+
branch develop
132+
checkout develop
133+
commit
134+
commit id: "Dev progress"
135+
branch feature/new-auth
136+
checkout feature/new-auth
137+
commit
138+
commit
139+
checkout develop
140+
merge feature/new-auth
141+
branch fix/login-bug
142+
checkout fix/login-bug
143+
commit
144+
checkout develop
145+
merge fix/login-bug
146+
checkout main
147+
merge develop tag: "v1.0.0"
148+
commit id: "v1.0.1"
149+
branch hotfix/urgent-fix
150+
checkout hotfix/urgent-fix
151+
commit
152+
checkout main
153+
merge hotfix/urgent-fix tag: "v1.0.2"
154+
checkout develop
155+
merge hotfix/urgent-fix
156+
```
157+
158+
## Rebase Guidelines
159+
160+
### When to Rebase
161+
162+
```bash
163+
# Keep feature branch up-to-date with main
164+
git checkout feature/your-feature-name
165+
git fetch origin
166+
git rebase origin/main
167+
```
168+
169+
### Interactive Rebase (Squash Commits)
170+
171+
```bash
172+
# Squash last 5 commits into 1 meaningful commit
173+
git rebase -i HEAD~5
174+
175+
# Change commits:
176+
# pick abc1234 First commit
177+
# squash def5678 Second commit
178+
# squash ghi9012 Third commit
179+
```
180+
181+
### Rebase Workflow
182+
183+
```bash
184+
# 1. Start with fresh branch
185+
git checkout feature/your-feature-name
186+
git rebase origin/main
187+
188+
# 2. Work normally (commit frequently)
189+
190+
# 3. Before merging, squash small commits
191+
git rebase -i origin/main
192+
193+
# 4. Force push (only after rebase)
194+
git push --force-with-lease origin feature/your-feature-name
195+
```
196+
197+
### Rebase vs Merge
198+
199+
| Operation | Rebase | Merge |
200+
|-----------|--------|-------|
201+
| **When to use** | Update feature branches | Merge to main/develop |
202+
| **History** | Clean, linear | Preserves merge commits |
203+
| **Example** | `git rebase origin/main` | `git merge feature/abc` |
204+
205+
### Safety Rules
206+
207+
1. **Never** rebase `main` or `develop` branches
208+
2. **Never** force push to shared branches
209+
3. **Always** use `--force-with-lease`
210+
4. **Rebase** only your own branches
211+
5. **Merge** when team has commits on your branch
212+
213+
### Conflict Resolution
214+
215+
```bash
216+
# During rebase
217+
git rebase origin/main
218+
219+
# Resolve conflicts in files
220+
221+
# Continue
222+
git add <files>
223+
git rebase --continue
224+
225+
# Or abort
226+
git rebase --abort
227+
```
228+
229+
## Rules
230+
231+
1. **Never** commit directly to `main` or `develop` (except merges)
232+
2. **Always** create a branch from `main` (solo) or `develop` (team)
233+
3. **Always** run tests before merging
234+
4. **Always** delete merged branches
235+
5. **Keep** branches short-lived (< 1 week for features)
236+
6. **Use** descriptive branch names
237+
7. **Tag** releases on `main` with semantic versioning (v1.0.0, v1.1.0, etc.)
238+
8. **Hotfix** branches must be created from `main`, not `develop`
239+
9. **Hotfix** merges must be tagged immediately (v1.0.2, v1.0.3, etc.)
240+
10. **Hotfix** must be back-merged to `develop` (if using team workflow)
241+
11. **Rebase** only feature/fix/hotfix branches, never main/develop
242+
12. **Force push** only with `--force-with-lease` and only on feature branches
243+
244+
## Release Process
245+
246+
### Solo Development
247+
```bash
248+
git checkout main
249+
git tag -a v1.0.0 -m "Release version 1.0.0"
250+
git push origin v1.0.0
251+
```
252+
253+
### Team Development
254+
```bash
255+
git checkout develop
256+
git checkout main
257+
git merge develop
258+
git tag -a v1.0.0 -m "Release version 1.0.0"
259+
git push origin v1.0.0
260+
```
261+
262+
## Conflict Resolution
263+
264+
```bash
265+
# Before merging, update your branch
266+
git checkout feature/your-feature-name
267+
git pull origin main
268+
269+
# Resolve conflicts in your files
270+
271+
# Complete merge
272+
git checkout main
273+
git merge feature/your-feature-name
274+
git branch -d feature/your-feature-name
275+
```

0 commit comments

Comments
 (0)