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