close
Skip to content

Commit c43aa95

Browse files
ryanwelcherryanwelcher
committed
Add readme
1 parent 8ce8f21 commit c43aa95

File tree

1 file changed

+308
-0
lines changed

1 file changed

+308
-0
lines changed

‎readme.md‎

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

0 commit comments

Comments
 (0)