close
Skip to content

Commit 5fca59b

Browse files
ryanwelcherryanwelcher
committed
Readme updates
1 parent 951828b commit 5fca59b

File tree

2 files changed

+359
-265
lines changed

2 files changed

+359
-265
lines changed

‎CONTRIBUTING.md‎

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
# Contributing to This Repository
2+
3+
Welcome! This guide explains how to contribute using our **simplified Git Flow** approach.
4+
5+
## 📋 Table of Contents
6+
7+
- [Branch Overview](#branch-overview)
8+
- [Branch Naming Conventions](#branch-naming-conventions)
9+
- [Workflow](#workflow)
10+
- [Pull Request Process](#pull-request-process)
11+
- [Quick Reference](#quick-reference)
12+
13+
---
14+
15+
## 🌳 Branch Overview
16+
17+
| Branch | Purpose | Deploys To |
18+
|--------|---------|------------|
19+
| `trunk` | Production-ready code (primary branch, source for all new branches) | **Production** |
20+
| `staging` | Integration branch for testing | **Staging Environment** |
21+
22+
> ⛔ **IMPORTANT: `staging` is NEVER merged into `trunk`**
23+
>
24+
> The `staging` branch is only used for testing purposes. When changes are approved, the **original working branch** is merged directly into `trunk`. This keeps our production branch clean and ensures we have full traceability of individual changes.
25+
26+
### Flow Summary
27+
28+
```
29+
┌─────────┐
30+
│ trunk │ ◄─── Source for ALL new branches
31+
└────┬────┘
32+
│
33+
│ (branch created from trunk)
34+
▼
35+
┌──────────────┐
36+
│ feature/ │
37+
│ bugfix/ │
38+
│ hotfix/ │
39+
└──────┬───────┘
40+
│
41+
├────────────────┐
42+
│ │
43+
▼ (direct merge) │
44+
┌─────────┐ │
45+
│ staging │ │
46+
└────┬────┘ │
47+
│ │
48+
▼ │
49+
┌─────────────┐ │
50+
│ Staging │ │
51+
│ Environment │ │
52+
│ (QA Testing)│ │
53+
└─────────────┘ │
54+
│ │
55+
│ Approved │
56+
│ │
57+
▼ ▼ (Pull Request)
58+
┌─────────┐ ┌─────────┐
59+
│ ✗ │ │ trunk │ ───► Production
60+
│ staging │ └─────────┘
61+
│ is NOT │
62+
│ merged │
63+
└─────────┘
64+
```
65+
66+
---
67+
68+
> 🚨 **NEVER MERGE `staging` INTO `trunk`**
69+
>
70+
> The `staging` branch may contain multiple features being tested simultaneously and could include work that is not yet approved. Always merge the original working branch directly into `trunk`.
71+
72+
---
73+
74+
## 📝 Branch Naming Conventions
75+
76+
Use the following prefixes for your branches:
77+
78+
| Type | Pattern | Example | Use Case |
79+
|------|---------|---------|----------|
80+
| Feature | `feature/short-description` | `feature/user-authentication` | New functionality |
81+
| Bug Fix | `bugfix/short-description` | `bugfix/login-validation` | Non-urgent fixes |
82+
| Hotfix | `hotfix/short-description` | `hotfix/critical-security-patch` | Urgent production fixes |
83+
84+
**Guidelines:**
85+
- Use lowercase letters
86+
- Use hyphens (`-`) to separate words
87+
- Keep names short but descriptive
88+
- Include ticket/issue number if applicable (e.g., `feature/123-user-auth`)
89+
90+
---
91+
92+
## 🔄 Workflow
93+
94+
The workflow is identical for all branch types. **The only difference is the branch name prefix** (`feature/`, `bugfix/`, or `hotfix/`).
95+
96+
### Step-by-Step Process
97+
98+
#### 1. Create Your Branch from Trunk
99+
100+
```bash
101+
git checkout trunk
102+
git pull origin trunk
103+
git checkout -b <type>/your-branch-name
104+
```
105+
106+
Replace `<type>` with `feature`, `bugfix`, or `hotfix` depending on your work.
107+
108+
#### 2. Make Your Changes
109+
110+
```bash
111+
# Make changes to your code
112+
git add .
113+
git commit -m "feat: add user login functionality"
114+
```
115+
116+
#### 3. Keep Your Branch Updated
117+
118+
```bash
119+
git fetch origin
120+
git rebase origin/trunk
121+
```
122+
123+
#### 4. Merge Directly into Staging (No PR Required)
124+
125+
```bash
126+
git checkout staging
127+
git pull origin staging
128+
git merge <type>/your-branch-name
129+
git push origin staging
130+
```
131+
132+
This deploys your changes to the **Staging Environment** for testing.
133+
134+
#### 5. Wait for QA Approval
135+
136+
Your changes will be tested in the staging environment.
137+
138+
#### 6. Open a Pull Request → `trunk`
139+
140+
- After approval, create a Pull Request from your branch **directly** to `trunk`
141+
- Do **NOT** merge staging into trunk
142+
- Once merged, your changes deploy to **Production**
143+
144+
### Visual Flow
145+
146+
```
147+
<type>/your-branch-name
148+
│
149+
├────► staging (direct merge, no PR)
150+
│ │
151+
│ ▼
152+
│ Staging Environment
153+
│ │
154+
│ QA Approval
155+
│ │
156+
│ ▼
157+
└────► trunk (Pull Request required)
158+
│
159+
▼
160+
Production Environment
161+
```
162+
163+
---
164+
165+
## 🔍 Pull Request Process
166+
167+
> 📝 **Note:** Pull Requests are only required when merging to `trunk`. You can merge directly to `staging` without a PR.
168+
169+
### Before Submitting a PR to Trunk
170+
171+
- [ ] Code has been tested in the staging environment
172+
- [ ] QA has approved the changes
173+
- [ ] Code follows project style guidelines
174+
- [ ] All tests pass locally
175+
- [ ] Branch is up to date with `trunk`
176+
- [ ] Commit messages are clear and descriptive
177+
- [ ] Documentation is updated (if applicable)
178+
179+
### PR Requirements
180+
181+
1. **Title:** Use a clear, descriptive title
182+
2. **Description:** Explain what changes were made and why
183+
3. **Reviewers:** Request at least one reviewer
184+
4. **Labels:** Add appropriate labels (feature, bugfix, etc.)
185+
186+
### Merge Strategy
187+
188+
| Target Branch | Method | PR Required |
189+
|---------------|--------|-------------|
190+
| `staging` | Direct merge | ❌ No |
191+
| `trunk` | Merge commit | ✅ Yes |
192+
193+
### Release Process
194+
195+
```
196+
┌──────────────────────────────────────────────────────────────────┐
197+
│ RELEASE FLOW │
198+
├──────────────────────────────────────────────────────────────────┤
199+
│ │
200+
│ 1. Create branch from trunk │
201+
│ trunk ─────► <type>/your-branch │
202+
│ │
203+
│ 2. Merge directly to staging (no PR required) │
204+
│ <type>/your-branch ─────► staging ─────► Staging Env │
205+
│ │
206+
│ 3. QA Testing & Approval │
207+
│ │
208+
│ 4. Open PR directly to trunk (NOT from staging!) │
209+
│ <type>/your-branch ─────► trunk ─────► Production Env │
210+
│ ▲ │
211+
│ │ │
212+
│ └─── Direct merge from working branch │
213+
│ │
214+
│ ⛔ staging ───✗───► trunk (NEVER DO THIS) │
215+
│ │
216+
└──────────────────────────────────────────────────────────────────┘
217+
```
218+
219+
---
220+
221+
## ⚡ Quick Reference
222+
223+
```bash
224+
# Start any new work (always from trunk)
225+
git checkout trunk && git pull
226+
git checkout -b <type>/description # feature/, bugfix/, or hotfix/
227+
228+
# Make your changes and commit
229+
git add .
230+
git commit -m "feat: description of change"
231+
232+
# Update your branch with latest trunk
233+
git fetch origin
234+
git rebase origin/trunk
235+
236+
# Merge to staging for testing (no PR needed)
237+
git checkout staging
238+
git pull origin staging
239+
git merge <type>/description
240+
git push origin staging
241+
242+
# After QA approval, create PR from your branch to trunk
243+
# (Do this via GitHub/GitLab UI)
244+
```
245+
246+
### Branch Rules Summary
247+
248+
| Rule | Description |
249+
|------|-------------|
250+
| **Create from** | Always create branches from `trunk` |
251+
| **Staging merge** | Direct merge (no PR required) |
252+
| **Trunk merge** | Pull Request required |
253+
| **Never** | Never merge `staging` into `trunk` |
254+
| **Never** | Never create branches from `staging` |
255+
256+
---
257+
258+
## ⛔ What NOT To Do
259+
260+
| Action | Why It's Wrong |
261+
|--------|----------------|
262+
| Merge `staging` into `trunk` | `staging` may contain untested or unapproved code |
263+
| Create branches from `staging` | `staging` is not the source of truth |
264+
| Skip testing in `staging` | Changes must be tested before production |
265+
| Merge to `trunk` before QA approval | Untested code could reach production |
266+
| Open a PR to `staging` | Direct merges are preferred for staging |
267+
268+
---
269+
270+
## 📌 Commit Message Format
271+
272+
We follow [Conventional Commits](https://www.conventionalcommits.org/):
273+
274+
```
275+
<type>: <short description>
276+
277+
[optional body]
278+
279+
[optional footer]
280+
```
281+
282+
**Types:**
283+
- `feat:` - New feature
284+
- `fix:` - Bug fix
285+
- `docs:` - Documentation changes
286+
- `style:` - Code style changes (formatting, etc.)
287+
- `refactor:` - Code refactoring
288+
- `test:` - Adding or updating tests
289+
- `chore:` - Maintenance tasks
290+
291+
**Examples:**
292+
```bash
293+
feat: add user registration endpoint
294+
fix: resolve null pointer in auth service
295+
docs: update API documentation
296+
```
297+
298+
---
299+
300+
## ❓ Questions?
301+
302+
If you have any questions about the contribution process, please:
303+
- Open an issue with the `question` label
304+
- Reach out to the maintainers
305+
306+
**Happy Contributing!** 🎉

0 commit comments

Comments
 (0)