|
2 | 2 |
|
3 | 3 | ## Branch Strategy |
4 | 4 |
|
5 | | -The project follows a structured branching workflow: |
| 5 | +The project uses two workflows depending on the scope of changes: |
| 6 | + |
| 7 | +### Patch Releases (default workflow) |
| 8 | + |
| 9 | +For incremental work (bug fixes, small features, improvements) that goes into the next patch version: |
6 | 10 |
|
7 | 11 | ``` |
8 | | -feature/fix/refactor branches → release branch (vX.Y.Z) → dev (staging/QA) → main (production) |
| 12 | +feature/fix/refactor branches → dev (release candidate) → main (production) |
9 | 13 | ``` |
10 | 14 |
|
11 | | -### Branch Types |
| 15 | +1. **Dev Branch**: Always holds the next release candidate (patch increment) |
| 16 | + - Feature/fix PRs are created directly against `dev` |
| 17 | + - Used for QA/staging before production |
| 18 | + - Always represents the next patch version (e.g., if main is v1.2.0, dev is the v1.2.1 candidate) |
12 | 19 |
|
13 | | -1. **Feature/Fix/Refactor Branches**: Created from the **release branch** for specific changes |
| 20 | +2. **Feature/Fix/Refactor Branches**: Created from `dev` |
14 | 21 | - Naming: `feat/<description>`, `fix/<description>`, `refactor/<description>` |
15 | | - - Example: `feat/token-holdings`, `fix/light-theme-colors`, `refactor/address-layout` |
16 | | - - PRs are created against the release branch |
17 | | - |
18 | | -2. **Release Branches**: Created for each release cycle |
19 | | - - Naming: `release/vX.Y.Z` (e.g., `release/v1.1.1`) |
20 | | - - All feature branches are merged here |
21 | | - - When features are complete, merged to `dev` for QA/staging |
| 22 | + - PRs are created against `dev` |
22 | 23 |
|
23 | | -3. **Dev Branch**: Staging/QA environment |
24 | | - - Receives merges from release branches |
25 | | - - Used for QA testing before production |
26 | | - - If fixes are needed during QA, PRs can be created directly against `dev` |
27 | | - |
28 | | -4. **Main Branch**: Production-ready code |
| 24 | +3. **Main Branch**: Production-ready code |
29 | 25 | - Only receives merges from `dev` after QA approval |
30 | | - - Always stable and deployable |
| 26 | + - Tagged with the version on merge |
31 | 27 |
|
32 | | -### Workflow Steps |
| 28 | +#### Patch Workflow Steps |
33 | 29 |
|
34 | | -1. Create or checkout the release branch: |
| 30 | +1. Create feature branch from `dev`: |
35 | 31 | ```bash |
36 | | - git checkout release/v1.1.1 |
37 | | - git pull origin release/v1.1.1 |
| 32 | + git checkout dev |
| 33 | + git pull origin dev |
| 34 | + git checkout -b feat/my-feature |
38 | 35 | ``` |
39 | 36 |
|
40 | | -2. Create feature branch from the release branch: |
| 37 | +2. Work on feature, commit changes following conventional commits |
| 38 | + |
| 39 | +3. Push and create PR to `dev`: |
41 | 40 | ```bash |
42 | | - git checkout -b feat/my-feature |
| 41 | + git push -u origin feat/my-feature |
| 42 | + gh pr create --base dev |
43 | 43 | ``` |
44 | 44 |
|
45 | | -3. Work on feature, commit changes following conventional commits |
| 45 | +4. After PR approval and merge to `dev`, delete feature branch |
46 | 46 |
|
47 | | -4. Push and create PR to the **release branch**: |
| 47 | +5. After QA approval, merge `dev` to `main`: |
48 | 48 | ```bash |
49 | | - git push -u origin feat/my-feature |
50 | | - gh pr create --base release/v1.1.1 |
| 49 | + git checkout main |
| 50 | + git merge dev |
| 51 | + git tag v1.2.1 |
| 52 | + git push origin main --tags |
51 | 53 | ``` |
52 | 54 |
|
53 | | -5. After PR approval and merge to release branch, delete feature branch |
| 55 | +### Minor/Major Releases (release branch workflow) |
| 56 | + |
| 57 | +For larger milestones with multiple coordinated changes (new features, breaking changes): |
54 | 58 |
|
55 | | -6. When release is ready for QA, merge release branch to `dev`: |
| 59 | +``` |
| 60 | +feature/fix/refactor branches → release branch (vX.Y.Z) → dev → main |
| 61 | +``` |
| 62 | + |
| 63 | +1. **Release Branches**: Created from `dev` for each release cycle |
| 64 | + - Naming: `release/vX.Y.Z` (e.g., `release/v1.3.0`) |
| 65 | + - Feature branches are created from and merged into the release branch |
| 66 | + - When features are complete, merged to `dev` for QA/staging |
| 67 | + |
| 68 | +2. **Feature Branches**: Created from the **release branch** |
| 69 | + - PRs are created against the release branch |
| 70 | + |
| 71 | +#### Release Branch Workflow Steps |
| 72 | + |
| 73 | +1. Create the release branch from `dev`: |
56 | 74 | ```bash |
57 | 75 | git checkout dev |
58 | | - git merge release/v1.1.1 |
59 | | - git push origin dev |
| 76 | + git checkout -b release/v1.3.0 |
| 77 | + git push -u origin release/v1.3.0 |
| 78 | + ``` |
| 79 | + |
| 80 | +2. Create feature branches from the release branch: |
| 81 | + ```bash |
| 82 | + git checkout release/v1.3.0 |
| 83 | + git checkout -b feat/my-feature |
60 | 84 | ``` |
61 | 85 |
|
62 | | -7. **QA/Staging fixes**: If issues are found during QA, create PRs directly against `dev`: |
| 86 | +3. Push and create PR to the **release branch**: |
| 87 | + ```bash |
| 88 | + git push -u origin feat/my-feature |
| 89 | + gh pr create --base release/v1.3.0 |
| 90 | + ``` |
| 91 | + |
| 92 | +4. When all features are merged, merge release branch to `dev` for QA: |
63 | 93 | ```bash |
64 | 94 | git checkout dev |
65 | | - git checkout -b fix/qa-issue |
66 | | - # ... fix the issue ... |
67 | | - gh pr create --base dev |
| 95 | + git merge release/v1.3.0 |
| 96 | + git push origin dev |
68 | 97 | ``` |
69 | 98 |
|
70 | | -8. After QA approval, merge `dev` to `main`: |
| 99 | +5. QA fixes go directly against `dev` |
| 100 | + |
| 101 | +6. After QA approval, merge `dev` to `main`: |
71 | 102 | ```bash |
72 | 103 | git checkout main |
73 | 104 | git merge dev |
74 | | - git tag v1.1.1 |
| 105 | + git tag v1.3.0 |
75 | 106 | git push origin main --tags |
76 | 107 | ``` |
77 | 108 |
|
|
0 commit comments