Skip to content

Commit fb61d49

Browse files
alexpmulealexpmule
committed
docs: add branch naming conventions pattern for api-console releases
- Documents fix/ vs build/ vs wrapper (no prefix) branch patterns - Explains why build/ prevents version conflicts - Includes examples from W-21368901 workflow - Provides validation checklist and common mistakes Related: W-21315032
1 parent 15cba4f commit fb61d49

1 file changed

Lines changed: 302 additions & 0 deletions

File tree

‎docs/team/patterns/branch-naming-conventions.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# Branch Naming Conventions for API Console v6
2+
3+
> **Last Updated**: 2026-03-03
4+
> **Owner**: ACM Team
5+
> **Purpose**: Standardize branch naming across api-console ecosystem
6+
7+
---
8+
9+
## Overview
10+
11+
The API Console v6 ecosystem consists of:
12+
1. **Individual components** (e.g., api-example-generator, api-type-document, api-navigation)
13+
2. **api-console** (main package that bundles components)
14+
3. **anypoint-api-console** (wrapper for Salesforce)
15+
16+
Different branch naming patterns are used depending on the type of change and repository.
17+
18+
---
19+
20+
## Branch Naming Patterns
21+
22+
### 1. `fix/W-XXXXX-description` - Component Bug Fixes
23+
24+
**Use when**: Fixing a bug in an individual component repository
25+
26+
**Applies to**:
27+
- `@api-components/api-example-generator`
28+
- `@api-components/api-type-document`
29+
- `@api-components/api-navigation`
30+
- `@api-components/api-summary`
31+
- `@api-components/api-documentation`
32+
- `@api-components/api-request`
33+
- All other `@api-components/*` packages
34+
35+
**Format**: `fix/W-XXXXXXXX-short-description`
36+
37+
**Examples**:
38+
```bash
39+
fix/W-21368901-deep-allof
40+
fix/W-12345678-grpc-schema-parsing
41+
fix/W-87654321-nullable-union-types
42+
```
43+
44+
**Workflow**:
45+
1. Create `fix/W-XXXXX-description` branch
46+
2. Implement fix + tests
47+
3. **DO NOT** run `npm version patch` in the branch
48+
4. Commit changes with conventional commit message
49+
5. Push branch
50+
6. Create PR
51+
7. **After merge**: GitHub Actions auto-publishes new version (e.g., 4.4.36)
52+
53+
**Why no version bump in branch**: Allows multiple fixes to be in progress simultaneously without version conflicts. GitHub Actions handles version bumping after merge.
54+
55+
---
56+
57+
### 2. `build/X.X.X` - API Console Releases
58+
59+
**Use when**: Creating a new api-console release that bundles multiple component updates
60+
61+
**Applies to**:
62+
- `mulesoft/api-console` (main repo)
63+
64+
**Format**: `build/X.X.X` where X.X.X is the **next** patch version
65+
66+
**Examples**:
67+
```bash
68+
build/6.6.62
69+
build/6.6.63
70+
build/6.7.0 # Minor version bump
71+
```
72+
73+
**Workflow**:
74+
1. Component fixes are already published (e.g., api-example-generator@4.4.36, api-type-document@4.2.42)
75+
2. Create `build/X.X.X` branch (calculate next version from package.json)
76+
3. Run `npm update @api-components/component-name` for each updated component
77+
4. Run `npm version patch` (bumps version in package.json)
78+
5. Commit all changes (package.json, package-lock.json)
79+
6. Push branch
80+
7. Create PR with title: `Release vX.X.X`
81+
8. **After merge**: GitHub Actions publishes api-console@X.X.X to npm
82+
83+
**Why `build/` not `fix/`**:
84+
- A release typically includes **multiple** component updates (3-5 components)
85+
- Each component may have different GUS work items
86+
- `build/` signals "this is a bundled release", not a single fix
87+
- Prevents confusion when multiple releases are prepared in parallel
88+
89+
**Version calculation**:
90+
- Read current version from `package.json`
91+
- Increment patch: `6.6.61` → `6.6.62`
92+
- Use incremented version in branch name
93+
94+
---
95+
96+
### 3. `X.X.X` - Wrapper Releases (No Prefix)
97+
98+
**Use when**: Updating anypoint-api-console wrapper with new api-console version
99+
100+
**Applies to**:
101+
- `mulesoft-emu/anypoint-api-console` (wrapper repo)
102+
103+
**Format**: `X.X.X` (direct number, **no prefix**)
104+
105+
**Examples**:
106+
```bash
107+
6.6.88
108+
6.6.89
109+
6.7.0
110+
```
111+
112+
**Workflow**:
113+
1. Wait for api-console@X.X.X to be published to npm (~5-10 min after merge)
114+
2. Create branch with wrapper version number (independent from api-console version)
115+
3. Update `builder/package.json` with new api-console dependency
116+
4. Delete `builder/package-lock.json` and `builder/node_modules` (mandatory)
117+
5. Run `npm install` in `builder/`
118+
6. Commit changes (NO version bump in root package.json)
119+
7. Push branch
120+
8. Create PR with title: `@W-XXXXXXXX: Release X.X.X`
121+
9. After merge: Manual or automated deployment
122+
123+
**Why no prefix**:
124+
- Historical convention in this repo
125+
- Wrapper versions are independent from api-console versions
126+
- Example: api-console 6.6.62 → wrapper 6.6.88
127+
128+
---
129+
130+
## Comparison Table
131+
132+
| Scenario | Branch Pattern | Repo | Version Bump in Branch? | Example |
133+
|----------|----------------|------|-------------------------|---------|
134+
| Fix bug in component | `fix/W-XXXXX-desc` | `@api-components/*` | ❌ No | `fix/W-21368901-deep-allof` |
135+
| Release api-console | `build/X.X.X` | `mulesoft/api-console` | ✅ Yes (`npm version patch`) | `build/6.6.62` |
136+
| Update wrapper | `X.X.X` | `mulesoft-emu/anypoint-api-console` | ❌ No | `6.6.88` |
137+
138+
---
139+
140+
## Why This Pattern?
141+
142+
### Problem: Version Conflicts
143+
If we used `fix/` branches in api-console and ran `npm version patch` in each:
144+
- Developer A: `fix/bug-1` → bumps to 6.6.62
145+
- Developer B: `fix/bug-2` → also bumps to 6.6.62
146+
- **Conflict**: Both branches claim the same version
147+
148+
### Solution: Separate Concerns
149+
- **Components**: `fix/` branches focus on code changes, version bump happens after merge
150+
- **api-console**: `build/` branches bundle multiple components, explicit version in branch name prevents conflicts
151+
- **Wrapper**: Direct version number, independent versioning
152+
153+
---
154+
155+
## Related GUS Work Items
156+
157+
### Components
158+
- Each fix has its own GUS work item
159+
- Format: `W-XXXXXXXX` (no prefix in branch name)
160+
- Example: `fix/W-21368901-deep-allof` → W-21368901
161+
162+
### api-console
163+
- Release may reference multiple GUS work items (from bundled components)
164+
- Commit message lists all related work items
165+
- PR body includes all component updates with their GUS tickets
166+
167+
### Wrapper
168+
- Typically has one "APIC Release" work item (reused across releases)
169+
- Example: W-21411326 (Type: User Story, 1 story point)
170+
- PR title always prefixed with `@W-XXXXXXXX:`
171+
172+
---
173+
174+
## Examples from Recent Work
175+
176+
### Scenario: Fix deeply nested allOf bug (W-21368901)
177+
178+
**Step 1: Fix in api-example-generator**
179+
```bash
180+
cd ~/mulesoft/context/products/api-console/v6/api-example-generator
181+
git checkout -b fix/W-21368901-deep-allof
182+
# Implement fix + tests
183+
git add src/ test/
184+
git commit -m "fix(W-21368901): add recursive property collection for deep allOf"
185+
# NO npm version patch here
186+
git push -u origin fix/W-21368901-deep-allof
187+
# Create PR → Merge → GitHub Actions publishes 4.4.36
188+
```
189+
190+
**Step 2: Fix in api-type-document**
191+
```bash
192+
cd ~/mulesoft/context/products/api-console/v6/api-type-document
193+
git checkout -b fix/W-21368901-deep-allof
194+
# Implement parallel fix
195+
git commit -m "fix(W-21368901): add recursive property collection"
196+
# NO npm version patch here
197+
git push -u origin fix/W-21368901-deep-allof
198+
# Create PR → Merge → GitHub Actions publishes 4.2.42
199+
```
200+
201+
**Step 3: Release api-console**
202+
```bash
203+
cd ~/mulesoft/context/products/api-console/v6/api-console
204+
git checkout -b build/6.6.62
205+
npm update @api-components/api-example-generator @api-components/api-type-document
206+
npm version patch # Bumps to 6.6.62
207+
git add package.json package-lock.json
208+
git commit -m "chore: bump version to 6.6.62
209+
210+
Updated components:
211+
- @api-components/api-example-generator: 4.4.35 → 4.4.36
212+
- @api-components/api-type-document: 4.2.41 → 4.2.42
213+
214+
Related: W-21368901"
215+
git push -u origin build/6.6.62
216+
# Create PR → Merge → GitHub Actions publishes 6.6.62
217+
```
218+
219+
**Step 4: Update wrapper**
220+
```bash
221+
cd ~/mulesoft/context/products/api-console/wrapper
222+
git checkout -b 6.6.88
223+
# Edit builder/package.json: "api-console": "6.6.62"
224+
cd builder
225+
rm package-lock.json && rm -rf node_modules && npm install
226+
cd ..
227+
git add builder/package.json builder/package-lock.json
228+
git commit -m "chore: update api-console to 6.6.62
229+
230+
Includes component updates:
231+
- @api-components/api-example-generator: 4.4.36
232+
- @api-components/api-type-document: 4.2.42
233+
234+
Related: W-21368901"
235+
git push -u origin 6.6.88
236+
gh pr create --title "@W-21411326: Release 6.6.88" --body "..."
237+
```
238+
239+
---
240+
241+
## Validation Checklist
242+
243+
Before creating branch:
244+
- [ ] Identified correct pattern (`fix/`, `build/`, or direct number)
245+
- [ ] For `build/`: Calculated next version from current package.json
246+
- [ ] For wrapper: Determined independent wrapper version
247+
- [ ] Have GUS work item numbers ready for commit messages
248+
249+
Before pushing:
250+
- [ ] Branch name follows convention
251+
- [ ] Version bump only in `build/` branches (not `fix/`)
252+
- [ ] Commit message references GUS work items
253+
- [ ] GPG signature correct (mulesoft-git or salesforce-git)
254+
255+
---
256+
257+
## Common Mistakes
258+
259+
### ❌ Wrong: Using `fix/` in api-console for releases
260+
```bash
261+
# DON'T DO THIS
262+
git checkout -b fix/W-21368901-deep-allof # Wrong for api-console
263+
npm version patch # Creates version conflict risk
264+
```
265+
266+
### ✅ Correct: Using `build/` in api-console
267+
```bash
268+
# DO THIS
269+
git checkout -b build/6.6.62 # Clear version intent
270+
npm version patch # Safe, version is in branch name
271+
```
272+
273+
### ❌ Wrong: Running `npm version patch` in component `fix/` branch
274+
```bash
275+
cd api-example-generator
276+
git checkout -b fix/W-12345-bug
277+
# ... make changes ...
278+
npm version patch # DON'T DO THIS - let CI handle it
279+
```
280+
281+
### ✅ Correct: Let CI handle component versioning
282+
```bash
283+
cd api-example-generator
284+
git checkout -b fix/W-12345-bug
285+
# ... make changes ...
286+
git commit -m "fix(W-12345): description"
287+
# Merge PR → CI auto-publishes with version bump
288+
```
289+
290+
---
291+
292+
## Questions?
293+
294+
Contact:
295+
- **API Console**: ACM Team (#api-console-cloud-sync)
296+
- **Pattern clarification**: Alex Pérez
297+
- **Documentation updates**: Submit PR to this file
298+
299+
---
300+
301+
**Last Updated**: 2026-03-03
302+
**Version**: 1.0

0 commit comments

Comments
 (0)