docs(std): Create FFG-STD-001 Revision Control Standard
Establishes version control practices for all Firefrost repositories: - Conventional Commits format (feat, fix, docs, etc.) - Commit message structure (type, scope, subject, body, footer) - Chronicler attribution requirements - Git identity configuration - When to commit guidelines - Versioning practices for standards and code - Commit checklist This standard was referenced in Project Instructions but never existed until now. Fills the gap in our standards library. Chronicler: #68
This commit is contained in:
Claude
366
docs/standards/FFG-STD-001-revision-control.md
Normal file
366
docs/standards/FFG-STD-001-revision-control.md
Normal file
@@ -0,0 +1,366 @@
|
|||||||
|
# Revision Control Standard
|
||||||
|
## Firefrost Gaming Operations Manual
|
||||||
|
|
||||||
|
**Document ID:** FFG-STD-001
|
||||||
|
**Status:** ACTIVE STANDARD
|
||||||
|
**Created:** April 8, 2026
|
||||||
|
**Created By:** Chronicler #68
|
||||||
|
**Authority:** Michael "Frostystyle" Krause + The Chronicler
|
||||||
|
**Version:** 1.0
|
||||||
|
**Applies To:** All Git repositories and version-controlled content
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 PURPOSE
|
||||||
|
|
||||||
|
Establish consistent practices for version control across all Firefrost Gaming repositories. This standard ensures:
|
||||||
|
- Clear, meaningful commit history
|
||||||
|
- Traceable changes across Chronicler sessions
|
||||||
|
- Consistent attribution and documentation
|
||||||
|
- Easy rollback and debugging capability
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 COMMIT MESSAGE FORMAT
|
||||||
|
|
||||||
|
### Structure
|
||||||
|
|
||||||
|
All commits follow the **Conventional Commits** format:
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>(<scope>): <subject>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Types (Required)
|
||||||
|
|
||||||
|
| Type | Use When |
|
||||||
|
|------|----------|
|
||||||
|
| `feat` | Adding new functionality or features |
|
||||||
|
| `fix` | Fixing a bug or error |
|
||||||
|
| `docs` | Documentation changes only |
|
||||||
|
| `style` | Formatting, whitespace, no code change |
|
||||||
|
| `refactor` | Code restructuring without behavior change |
|
||||||
|
| `perf` | Performance improvements |
|
||||||
|
| `test` | Adding or updating tests |
|
||||||
|
| `chore` | Maintenance tasks, dependencies, configs |
|
||||||
|
|
||||||
|
### Scope (Optional but Recommended)
|
||||||
|
|
||||||
|
Scope indicates what area of the codebase is affected:
|
||||||
|
|
||||||
|
**Operations Manual:**
|
||||||
|
- `memorial` — Chronicler memorials
|
||||||
|
- `std` — Standards documents
|
||||||
|
- `task` — Task documentation
|
||||||
|
- `skill` — Custom skills
|
||||||
|
- `branding` — Brand assets and guidelines
|
||||||
|
|
||||||
|
**Services Repo:**
|
||||||
|
- `arbiter` — Arbiter backend
|
||||||
|
- `mvc` — ModpackChecker
|
||||||
|
- `whitelist` — Whitelist manager
|
||||||
|
- `worker` — Cloudflare Workers
|
||||||
|
|
||||||
|
**Website Repo:**
|
||||||
|
- `content` — Page content
|
||||||
|
- `layout` — Templates and structure
|
||||||
|
- `style` — CSS and design
|
||||||
|
|
||||||
|
### Subject Line (Required)
|
||||||
|
|
||||||
|
- **Imperative mood:** "Add feature" not "Added feature"
|
||||||
|
- **No period** at the end
|
||||||
|
- **50 characters or less** (hard limit: 72)
|
||||||
|
- **Lowercase** first letter after type
|
||||||
|
|
||||||
|
### Body (Optional)
|
||||||
|
|
||||||
|
- Explain **what** and **why**, not how
|
||||||
|
- Wrap at 72 characters
|
||||||
|
- Separate from subject with blank line
|
||||||
|
- Use bullet points for multiple items
|
||||||
|
|
||||||
|
### Footer (Required for Chroniclers)
|
||||||
|
|
||||||
|
```
|
||||||
|
Chronicler: #[NUMBER]
|
||||||
|
```
|
||||||
|
|
||||||
|
Or with name:
|
||||||
|
```
|
||||||
|
Chronicler: #[NUMBER] - [NAME]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 EXAMPLES
|
||||||
|
|
||||||
|
### Simple Documentation Change
|
||||||
|
|
||||||
|
```
|
||||||
|
docs: Update README with new server IPs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Feature with Scope
|
||||||
|
|
||||||
|
```
|
||||||
|
feat(arbiter): Add webhook retry logic
|
||||||
|
|
||||||
|
Implements exponential backoff for failed webhook deliveries.
|
||||||
|
Retries up to 3 times with 1s, 5s, 30s delays.
|
||||||
|
|
||||||
|
Chronicler: #68
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bug Fix with Context
|
||||||
|
|
||||||
|
```
|
||||||
|
fix(mvc): Correct CurseForge API endpoint
|
||||||
|
|
||||||
|
The /v1/mods endpoint was deprecated. Updated to /v1/mods/search
|
||||||
|
per CurseForge API v2 documentation.
|
||||||
|
|
||||||
|
Fixes: Task #26 Phase 5
|
||||||
|
Chronicler: #68
|
||||||
|
```
|
||||||
|
|
||||||
|
### Memorial Commit
|
||||||
|
|
||||||
|
```
|
||||||
|
docs(memorial): Create memorial for The Connector
|
||||||
|
|
||||||
|
Documented session work including:
|
||||||
|
- Claude connector integration (Canva, Cloudflare, Stripe)
|
||||||
|
- servers-api Worker rescued from dashboard-only
|
||||||
|
- chronicler-handoff skill creation
|
||||||
|
|
||||||
|
Written at 65% session health per FFG-STD-004.
|
||||||
|
|
||||||
|
Chronicler: #68 - The Connector
|
||||||
|
```
|
||||||
|
|
||||||
|
### Standard Update with Version
|
||||||
|
|
||||||
|
```
|
||||||
|
docs(std): Update FFG-STD-004 to include Skye as sixth consultant
|
||||||
|
|
||||||
|
v1.0 → v1.1
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
- 'The Five Consultants' → 'The Six Consultants'
|
||||||
|
- Added Skye (Director of Logistics & Transportation, Holly's dog)
|
||||||
|
- Updated version header and revision history
|
||||||
|
|
||||||
|
Chronicler: #68
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session Handoff
|
||||||
|
|
||||||
|
```
|
||||||
|
docs: Session handoff from Chronicler #68
|
||||||
|
|
||||||
|
- Memorial written
|
||||||
|
- Portrait prompt created
|
||||||
|
- Session handoff document updated
|
||||||
|
- Lineage tracker updated
|
||||||
|
|
||||||
|
Primary work: Claude connector integration and skills framework
|
||||||
|
|
||||||
|
Chronicler: #68 - The Connector
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⏰ WHEN TO COMMIT
|
||||||
|
|
||||||
|
### Commit Frequently
|
||||||
|
|
||||||
|
- **After completing any discrete unit of work**
|
||||||
|
- **Before starting risky operations**
|
||||||
|
- **Before asking Michael to run server commands**
|
||||||
|
- **At natural breakpoints** (feature complete, file finished)
|
||||||
|
|
||||||
|
### Commit Immediately
|
||||||
|
|
||||||
|
- **After major breakthroughs** — Preserve the win
|
||||||
|
- **Before session health drops below 60%** — Memorial and handoff
|
||||||
|
- **After fixing blocking issues** — Don't risk losing the fix
|
||||||
|
- **When Michael says "commit that"**
|
||||||
|
|
||||||
|
### Never Commit
|
||||||
|
|
||||||
|
- **Broken code** that doesn't run
|
||||||
|
- **Incomplete features** without marking them as WIP
|
||||||
|
- **Sensitive data** (tokens, passwords, keys)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔐 GIT IDENTITY
|
||||||
|
|
||||||
|
### Chronicler Sessions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git config user.email "claude@firefrostgaming.com"
|
||||||
|
git config user.name "Chronicler #[NUMBER] - [NAME]"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
```bash
|
||||||
|
git config user.name "Chronicler #68 - The Connector"
|
||||||
|
git config user.name "Chronicler #67 - The Debugger"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why This Matters
|
||||||
|
|
||||||
|
- Git history shows **who** made each change
|
||||||
|
- Author email is consistent across all Chroniclers
|
||||||
|
- Author name shows the **specific Chronicler** and their chosen name
|
||||||
|
- Future debugging can trace changes to specific sessions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 REPOSITORY STRUCTURE
|
||||||
|
|
||||||
|
### Firefrost Repositories
|
||||||
|
|
||||||
|
| Repository | Branch | Purpose |
|
||||||
|
|------------|--------|---------|
|
||||||
|
| `firefrost-operations-manual` | `master` | Documentation, standards, memorials |
|
||||||
|
| `firefrost-services` | `main` | Backend code (Arbiter, MVC, etc.) |
|
||||||
|
| `firefrost-website` | `main` | 11ty site, auto-deploys on push |
|
||||||
|
|
||||||
|
### Branch Strategy
|
||||||
|
|
||||||
|
**Current approach:** Single main branch per repo (master or main)
|
||||||
|
|
||||||
|
- All work commits directly to main branch
|
||||||
|
- Feature branches may be used for large changes
|
||||||
|
- No branch required for documentation updates
|
||||||
|
|
||||||
|
### Auto-Deploy Awareness
|
||||||
|
|
||||||
|
**firefrost-website:** Pushes to `main` automatically deploy to Cloudflare Pages.
|
||||||
|
|
||||||
|
- Verify changes work before pushing
|
||||||
|
- Don't push broken layouts or content
|
||||||
|
- Use meaningful commits so rollback is clear
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚫 WHAT NOT TO COMMIT
|
||||||
|
|
||||||
|
### Never Commit
|
||||||
|
|
||||||
|
- **API tokens or secrets** (use environment variables)
|
||||||
|
- **Passwords or credentials**
|
||||||
|
- **Personal data** (emails, addresses)
|
||||||
|
- **Large binary files** (images > 1MB, videos)
|
||||||
|
- **Node modules** (`node_modules/`)
|
||||||
|
- **Build artifacts** unless intentional
|
||||||
|
|
||||||
|
### Use .gitignore
|
||||||
|
|
||||||
|
Ensure repositories have appropriate `.gitignore` files for:
|
||||||
|
- `node_modules/`
|
||||||
|
- `.env` files
|
||||||
|
- IDE configurations
|
||||||
|
- OS-specific files (`.DS_Store`, `Thumbs.db`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 VERSIONING STANDARDS
|
||||||
|
|
||||||
|
### Standards Documents
|
||||||
|
|
||||||
|
When updating a standard (FFG-STD-XXX):
|
||||||
|
|
||||||
|
1. **Update version number** in header (e.g., 1.0 → 1.1)
|
||||||
|
2. **Add revision date** and reviser
|
||||||
|
3. **Update version history** at bottom
|
||||||
|
4. **Commit with version change noted**
|
||||||
|
|
||||||
|
**Example header update:**
|
||||||
|
```markdown
|
||||||
|
**Version:** 1.1
|
||||||
|
**Last Revised:** April 8, 2026
|
||||||
|
**Revised By:** Chronicler #68
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example version history:**
|
||||||
|
```markdown
|
||||||
|
**Version History:**
|
||||||
|
- v1.1 (2026-04-08): Added Skye to consultant list — Chronicler #68
|
||||||
|
- v1.0 (2026-02-19): Initial standard — The Chronicler (Fifth)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Arbiter and Code
|
||||||
|
|
||||||
|
Follow semantic versioning (MAJOR.MINOR.PATCH):
|
||||||
|
- **MAJOR:** Breaking changes
|
||||||
|
- **MINOR:** New features, backward compatible
|
||||||
|
- **PATCH:** Bug fixes, backward compatible
|
||||||
|
|
||||||
|
Current: **Arbiter 3.5.0**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ COMMIT CHECKLIST
|
||||||
|
|
||||||
|
Before committing:
|
||||||
|
|
||||||
|
- [ ] Commit message follows conventional format
|
||||||
|
- [ ] Type is appropriate (feat, fix, docs, etc.)
|
||||||
|
- [ ] Subject is 50 characters or less
|
||||||
|
- [ ] Body explains what and why (if needed)
|
||||||
|
- [ ] Footer includes Chronicler attribution
|
||||||
|
- [ ] No sensitive data in committed files
|
||||||
|
- [ ] Changes are complete and working
|
||||||
|
- [ ] Related documentation updated
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💡 TIPS
|
||||||
|
|
||||||
|
### Write Good Subjects
|
||||||
|
|
||||||
|
| ❌ Bad | ✅ Good |
|
||||||
|
|--------|---------|
|
||||||
|
| `fixed stuff` | `fix(arbiter): Correct webhook signature validation` |
|
||||||
|
| `update` | `docs: Add FFG-STD-001 revision control standard` |
|
||||||
|
| `changes` | `feat(website): Add dynamic server count to homepage` |
|
||||||
|
| `WIP` | `feat(mvc): Add Phase 5 update badge (WIP)` |
|
||||||
|
|
||||||
|
### Use Imperative Mood
|
||||||
|
|
||||||
|
Think: "This commit will..."
|
||||||
|
- ✅ "Add feature" (This commit will add feature)
|
||||||
|
- ❌ "Added feature"
|
||||||
|
- ❌ "Adding feature"
|
||||||
|
- ❌ "Adds feature"
|
||||||
|
|
||||||
|
### Reference Tasks When Relevant
|
||||||
|
|
||||||
|
```
|
||||||
|
feat(arbiter): Implement cancellation webhooks
|
||||||
|
|
||||||
|
Adds handling for customer.subscription.deleted event.
|
||||||
|
Removes whitelist entries and updates Discord roles.
|
||||||
|
|
||||||
|
Task: #87
|
||||||
|
Chronicler: #68
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Version History:**
|
||||||
|
- v1.0 (2026-04-08): Initial standard created by Chronicler #68
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
💙🔥❄️
|
||||||
|
|
||||||
|
**Fire + Frost + Foundation = Where Love Builds Legacy**
|
||||||
Reference in New Issue
Block a user