Add Part 10 — Git workflow
- Commit message format (imperative mood, 50 char subject, area prefixes) - Commit early/often philosophy - When to amend vs. new commit - Push guidelines (never force main, destructive operations need approval) - Repository hygiene (what to commit, .gitignore maintenance) - Signed commits noted for future
This commit is contained in:
James
parent
199495cdd8
commit
00f21464c3
|
|
@ -1180,4 +1180,105 @@ The feature will mature separately from these architectural principles.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Part 10 — Git workflow
|
||||||
|
|
||||||
|
### Commit philosophy
|
||||||
|
|
||||||
|
**Commit early, commit often.** A commit is a save point, not a publish event.
|
||||||
|
- One logical change per commit — don't mix bug fix + refactoring + new feature
|
||||||
|
- If you can't explain the commit in one sentence, it's too big — split it
|
||||||
|
- Work-in-progress commits are fine locally; clean up before sharing
|
||||||
|
|
||||||
|
### Commit message format
|
||||||
|
|
||||||
|
```
|
||||||
|
<subject>: <what changed>
|
||||||
|
|
||||||
|
<body>: <why it changed> (optional but encouraged)
|
||||||
|
|
||||||
|
<footer>: <references> (issue #123, fixes, etc.)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Subject line rules:**
|
||||||
|
- Imperative mood: "Add rate limiter" not "Added rate limiter"
|
||||||
|
- No period at end
|
||||||
|
- Max 50 characters (GitHub truncates at 72)
|
||||||
|
- Prefix with area: `api:`, `lib:`, `web:`, `crypto:`, `docs:`
|
||||||
|
|
||||||
|
**Good:**
|
||||||
|
```
|
||||||
|
api: add per-agent IP whitelist middleware
|
||||||
|
|
||||||
|
Implements Threat C defense: first contact fills whitelist,
|
||||||
|
subsequent requests rejected if IP not in list. Supports CIDR
|
||||||
|
and FQDN in addition to exact IPs.
|
||||||
|
|
||||||
|
Fixes #456
|
||||||
|
```
|
||||||
|
|
||||||
|
**Bad:**
|
||||||
|
```
|
||||||
|
changes
|
||||||
|
|
||||||
|
lots of changes to the code including some fixes and also
|
||||||
|
refactored the handler and added new feature for agents
|
||||||
|
```
|
||||||
|
|
||||||
|
### When to commit vs. amend
|
||||||
|
|
||||||
|
**Amend** (rewrite history) for:
|
||||||
|
- Fix typo in commit you just made
|
||||||
|
- Add file you forgot to stage
|
||||||
|
- Improve commit message
|
||||||
|
|
||||||
|
**New commit** for:
|
||||||
|
- Any change that has been pushed (even to your own branch)
|
||||||
|
- Changes that logically separate from previous work
|
||||||
|
- Anything another developer might have based work on
|
||||||
|
|
||||||
|
### Push guidelines
|
||||||
|
|
||||||
|
**Never force push to `main` or `master`.** Ever.
|
||||||
|
|
||||||
|
**Branch workflow:**
|
||||||
|
1. Create feature branch: `git checkout -b feature/agent-lockdown`
|
||||||
|
2. Commit work-in-progress freely
|
||||||
|
3. Before push: `git rebase -i main` to clean up (squash "fix typo" commits)
|
||||||
|
4. Push branch: `git push -u origin feature/agent-lockdown`
|
||||||
|
5. Open PR (when we have CI), or merge with `--no-ff` for feature visibility
|
||||||
|
|
||||||
|
**Destructive operations require explicit approval:**
|
||||||
|
- `git reset --hard`
|
||||||
|
- `git push --force` (any branch)
|
||||||
|
- `git filter-branch` or `git filter-repo`
|
||||||
|
- Branch deletion with unmerged commits
|
||||||
|
|
||||||
|
State: "About to [destructive operation] on [branch]. This will [effect].
|
||||||
|
Alternative: [safer option]. Proceed?"
|
||||||
|
|
||||||
|
### Repository hygiene
|
||||||
|
|
||||||
|
**What we commit:**
|
||||||
|
- Source code
|
||||||
|
- Generated code that's not reproducible (rare)
|
||||||
|
- Documentation
|
||||||
|
- Configuration templates (`.env.example`, not `.env`)
|
||||||
|
|
||||||
|
**What we DO NOT commit:**
|
||||||
|
- Secrets (keys, passwords, tokens)
|
||||||
|
- Build artifacts (`*.o`, `*.a`, binaries)
|
||||||
|
- Dependencies (vendor them or use go.mod)
|
||||||
|
- User data, vault files, logs
|
||||||
|
|
||||||
|
**`.gitignore` maintenance:**
|
||||||
|
- If a file is generated or contains secrets, add it to `.gitignore`
|
||||||
|
- Review `git status` before every commit — nothing should surprise you
|
||||||
|
|
||||||
|
### Signed commits (future)
|
||||||
|
|
||||||
|
When we add contributor access beyond core team, signed commits (SSH or GPG)
|
||||||
|
will be required. All commits must be verifiable.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Foundation First. No mediocrity. Ever.*
|
*Foundation First. No mediocrity. Ever.*
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue