Version Control Best Practices
Overview
This skill defines version control standards for all work products beyond just git - including documentation versions, knowledge entries, configuration, and data. Consistent version control practices enable traceability, recovery, and collaboration.
When to Use
- When committing any change to shared repositories
- When creating versions of documents, knowledge entries, or configurations
- When branching, merging, or managing parallel work streams
- When tagging releases or important milestones
- Don't use when: Working only on local drafts not yet ready for shared storage
Core Procedures
Step 1: Commit Standards
Every commit must have:
- Clear message: Start with verb, describe WHAT changed and WHY (not just "update" or "fix")
- Atomic: One logical change per commit (don't mix unrelated changes)
- Attributed: Correct author information
- Tested: Don't commit known-broken code to shared branches
Message format:
[type]: brief description
Detailed explanation if needed.
Related: [ticket/issue number if applicable]
Types: feat, fix, docs, refactor, test, chore, config, knowledge
Step 2: Branch Strategy
- main/master: Always deployable, protected branch
- develop: Integration branch for features (if using gitflow)
- feature/name: One branch per feature or task
- hotfix/name: Urgent fixes to production
- release/version: Stabilization before release
- Branch names use lowercase-with-dashes
Step 3: Version Numbering
Use semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR: Breaking changes that require user action
- MINOR: New features that are backward compatible
- PATCH: Bug fixes and minor improvements
For documentation/knowledge:
- Major structural rewrites
- New content sections added
- Corrections, clarifications, updates
Step 4: Knowledge Versioning
For non-code assets (knowledge, documentation):
- Track version in document frontmatter
- Maintain changelog at top of significant documents
- Use tags to mark: current, deprecated, archived, experimental
- Never delete, only supersede or archive
Step 5: Merge and Review
- Never push directly to main (if protected)
- Create pull request or merge request for all changes
- At least one reviewer for significant changes
- Resolve all conflicts before merging
- Delete branches after merging
Quality Checklist
Error Handling
- Error: Accidentally committed secrets or sensitive data
Response: Immediately revoke secret, force push to rewrite history, rotate all potentially exposed secrets
- Error: Merge conflict in critical file
Response: Don't force merge, get input from both authors, ensure both intents preserved
- Error: Committed broken code to main
Response: Revert immediately, fix on separate branch, improve guardrails to prevent recurrence
Cross-Team Integration
Related Skills: finishing-a-development-branch, using-git-worktrees, requesting-code-review, knowledge-capture
Used By: ALL agents working with shared repositories, especially developers, documenters, knowledge managers
1---2name: version-control-best-practices3description: Use when managing versions of code, documentation, knowledge, or configuration. This skill provides standardized version control practices across all repositories and knowledge stores, ensuring consistency, traceability, and recoverability.4---56# Version Control Best Practices78## Overview9This skill defines version control standards for all work products beyond just git - including documentation versions, knowledge entries, configuration, and data. Consistent version control practices enable traceability, recovery, and collaboration.1011## When to Use12- When committing any change to shared repositories13- When creating versions of documents, knowledge entries, or configurations14- When branching, merging, or managing parallel work streams15- When tagging releases or important milestones16- **Don't use when:** Working only on local drafts not yet ready for shared storage1718## Core Procedures1920### Step 1: Commit Standards21Every commit must have:22- **Clear message:** Start with verb, describe WHAT changed and WHY (not just "update" or "fix")23- **Atomic:** One logical change per commit (don't mix unrelated changes)24- **Attributed:** Correct author information25- **Tested:** Don't commit known-broken code to shared branches2627Message format:28```29[type]: brief description3031Detailed explanation if needed.3233Related: [ticket/issue number if applicable]34```3536Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `config`, `knowledge`3738### Step 2: Branch Strategy39- **main/master:** Always deployable, protected branch40- **develop:** Integration branch for features (if using gitflow)41- **feature/name:** One branch per feature or task42- **hotfix/name:** Urgent fixes to production43- **release/version:** Stabilization before release44- Branch names use lowercase-with-dashes4546### Step 3: Version Numbering47Use semantic versioning (MAJOR.MINOR.PATCH):48- **MAJOR:** Breaking changes that require user action49- **MINOR:** New features that are backward compatible50- **PATCH:** Bug fixes and minor improvements5152For documentation/knowledge:53- Major structural rewrites54- New content sections added55- Corrections, clarifications, updates5657### Step 4: Knowledge Versioning58For non-code assets (knowledge, documentation):59- Track version in document frontmatter60- Maintain changelog at top of significant documents61- Use tags to mark: current, deprecated, archived, experimental62- Never delete, only supersede or archive6364### Step 5: Merge and Review65- Never push directly to main (if protected)66- Create pull request or merge request for all changes67- At least one reviewer for significant changes68- Resolve all conflicts before merging69- Delete branches after merging7071## Quality Checklist72- [ ] All commits follow message format73- [ ] Branch naming follows convention74- [ ] Version numbers follow semantic versioning75- [ ] No broken code committed to shared branches76- [ ] All merges are reviewed before completion77- [ ] Old versions properly archived, not deleted7879## Error Handling80- **Error:** Accidentally committed secrets or sensitive data81 **Response:** Immediately revoke secret, force push to rewrite history, rotate all potentially exposed secrets82- **Error:** Merge conflict in critical file83 **Response:** Don't force merge, get input from both authors, ensure both intents preserved84- **Error:** Committed broken code to main85 **Response:** Revert immediately, fix on separate branch, improve guardrails to prevent recurrence8687## Cross-Team Integration88**Related Skills:** finishing-a-development-branch, using-git-worktrees, requesting-code-review, knowledge-capture89**Used By:** ALL agents working with shared repositories, especially developers, documenters, knowledge managers
Construct-AI-primary