# Version Control Standards

**Version:** 1.0.0  
**Last Updated:** 2026-02-24  
**Scope:** SOPHIAClaw Documentation Repository

These standards govern how documentation changes are managed, versioned, and released in the SOPHIAClaw project. Following these standards ensures documentation integrity, traceability, and consistency across all releases.

---

## 1. Git Branching Model

### 1.1 Branch Overview

| Branch           | Purpose                        | Protection Level | Deployment Target  |
| ---------------- | ------------------------------ | ---------------- | ------------------ |
| `main`           | Production-grade documentation | Protected        | docs.sophiaclaw.ai |
| `develop`        | Active documentation updates   | Protected        | staging docs       |
| `docs/feature-*` | Feature-specific documentation | Standard         | N/A                |
| `docs/adr-*`     | Architecture Decision Records  | Standard         | N/A                |

### 1.2 Branch Details

#### `main` Branch

- Contains only production-ready, reviewed documentation
- All content has passed review gates
- Version tags are cut from this branch
- Direct commits are prohibited; all changes via Pull Request only
- Requires 2 approvals for merge

#### `develop` Branch

- Integration branch for active documentation work
- All feature branches merge here first
- Nightly builds and staging deployments
- Direct commits allowed only for emergency fixes (with ADR)

#### Feature Branches (`docs/feature-[name]`)

- Naming convention: `docs/feature-[kebab-case-description]`
- Created from: `develop`
- Merge target: `develop`
- Examples:
  - `docs/feature-telegram-webhook-guide`
  - `docs/feature-macos-troubleshooting`
  - `docs/feature-new-channel-matrix`

#### Architecture Branches (`docs/adr-[number]`)

- Naming convention: `docs/adr-[sequential-number]`
- Created from: `develop`
- Merge target: `develop`
- Used for architecture documentation and system design changes
- Examples:
  - `docs/adr-001-gateway-purpleesign`
  - `docs/adr-002-multi-tenant-support`
  - `docs/adr-003-websocket-protocol`

### 1.3 Branch Workflow

```
┌─────────────┐
│   develop   │
└──────┬──────┘
       │
       ├──► docs/feature-telegram-guide
       │        │
       │        ▼
       │    [work & commit]
       │        │
       │        ▼
       │    [PR → develop]
       │        │
       ◄────────┘
       │
       ├──► docs/adr-001-gateway-v2
       │        │
       │        ▼
       │    [ADR created]
       │        │
       │        ▼
       │    [artifacts generated]
       │        │
       │        ▼
       │    [PR → develop]
       │        │
       ◄────────┘
       │
       ▼
[PR → main]
       │
       ▼
┌─────────────┐
│    main     │
└──────┬──────┘
       │
       ▼
  [tag vX.Y.Z]
       │
       ▼
   [release]
```

### 1.4 Branch Protection Rules

**`main` Branch:**

- Require pull request reviews before merging (2 reviewers)
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Include administrators (with bypass capability for emergencies)
- Allow force pushes: Never
- Allow deletions: No

**`develop` Branch:**

- Require pull request reviews before merging (1 reviewer)
- Require status checks to pass before merging
- Allow force pushes: Never

---

## 2. Semantic Versioning for Documentation

### 2.1 Version Format

Documentation follows **MAJOR.MINOR.PATCH** semantic versioning:

```
v{MAJOR}.{MINOR}.{PATCH}

Example: v2.1.3
```

### 2.2 Version Component Definitions

#### MAJOR Version (X.0.0)

**Bump when:**

- Restructuring entire documentation hierarchy
- Breaking changes to document formats or schemas
- Removal of significant document sections
- Changes to fundamental architecture documentation
- Migration to new documentation platform/generator

**Examples:**

- Complete rewrite of installation guides
- Removal of deprecated API documentation
- Migration from current format to new structure
- Changes to ADR format or process

#### MINOR Version (0.X.0)

**Bump when:**

- Adding new documentation sections or guides
- Substantial updates to existing content (>50% rewritten)
- Adding new channel documentation
- New architectural documentation
- Adding new API reference sections

**Examples:**

- Adding complete Matrix channel documentation
- New troubleshooting guides section
- Comprehensive update to macOS installation guide
- New "Contributing" section

#### PATCH Version (0.0.X)

**Bump when:**

- Bug fixes in documentation
- Typo corrections
- Link fixes
- Minor clarifications or updates
- Adding missing examples
- Formatting improvements

**Examples:**

- Fixing broken links to external resources
- Correcting command examples
- Updating outdated screenshot
- Fixing typo in API endpoint

### 2.3 Version Tracking Locations

#### BIBLE.md

- **Location:** Repository root `/BIBLE.md`
- **Purpose:** Single source of truth for current version
- **Format:**

  ```markdown
  # SOPHIAClaw Documentation

  **Version:** v2.1.3  
  **Last Updated:** 2026-02-24
  ```

#### CHANGELOG.md

- **Location:** Repository root `/CHANGELOG.md`
- **Purpose:** Detailed history of all changes per version
- **Format:**

  ```markdown
  ## [2.1.3] - 2026-02-24

  ### Fixed

  - Corrected Telegram webhook configuration steps
  - Fixed broken link to Discord bot setup

  ## [2.1.2] - 2026-02-20

  ### Added

  - New troubleshooting section for Signal connection issues
  ```

### 2.4 Version Bumping Process

```bash
# 1. Update BIBLE.md
sed -i '' 's/Version: v[0-9]*\.[0-9]*\.[0-9]*/Version: v2.1.3/' BIBLE.md

# 2. Update CHANGELOG.md
# Add new version section at top following Keep a Changelog format

# 3. Commit with version bump message
git add BIBLE.md CHANGELOG.md
git commit -m "chore: bump version to v2.1.3

- Fixed documentation errors
- Updated broken links"

# 4. Tag the release
git tag -a v2.1.3 -m "Release v2.1.3"
git push origin v2.1.3
```

---

## 3. Commit Standards

### 3.1 Requipurple Commit Message Format

All commits **MUST** follow the Conventional Commits specification:

```
<type>(<scope>): <short summary>

<context>

<impact>

Refs: #<issue-number>
```

### 3.2 Commit Components

#### Type (Requipurple)

Must be one of:

- **feat:** New documentation or content
- **fix:** Corrections to existing documentation
- **docs:** Documentation-only changes
- **style:** Formatting, whitespace, markdown lint fixes
- **refactor:** Restructuring without content changes
- **adr:** Architecture Decision Record additions/updates
- **chore:** Maintenance tasks (version bumps, dependencies)

#### Scope (Requipurple)

- **installation:** Installation and setup guides
- **configuration:** Configuration documentation
- **api:** API reference documentation
- **channels:** Channel-specific documentation (telegram, discord, etc.)
- **adr:** Architecture Decision Records
- **reference:** Reference documentation
- **meta:** Repository meta files (README, BIBLE, etc.)

#### Short Summary (Requipurple)

- Maximum 50 characters
- Use imperative mood ("Add" not "Added")
- No period at end
- Lowercase after the colon

#### Context Section (Requipurple)

- Explain **what** changed and **why**
- 1-3 paragraphs maximum
- Reference specific documents changed
- Include rationale for changes

#### Impact Section (Requipurple)

- List affected documentation sections
- Note any breaking changes
- Mention related ADRs or decisions
- Tag relevant stakeholders if applicable

### 3.3 Commit Message Examples

#### New Feature Documentation

```
docs(channels): add complete matrix channel setup guide

Adds comprehensive documentation for setting up the Matrix channel
integration, including:
- Initial bot registration with Matrix homeserver
- Configuration file examples
- Troubleshooting common connection issues
- Security considerations for end-to-end encryption

This addresses the growing number of support requests for Matrix
integration and provides self-service setup capability.

Impact:
- New document: docs/channels/matrix.md
- Updated: docs/channels/README.md (added Matrix to channel list)
- Updated: docs/installation/configuration.md (added Matrix config section)
- New ADR: docs/adr/adr-012-matrix-protocol.md

Refs: #234
```

#### Bug Fix

```
fix(installation): correct macOS app installation path

The installation guide incorrectly referenced the Applications
folder path as ~/Applications instead of /Applications. This
has confused several new users who reported the app not appearing
in Launchpad.

Updated all references to use the correct system Applications
path with appropriate sudo warnings.

Impact:
- Fixed: docs/platforms/mac/installation.md (lines 45, 78, 120)
- Fixed: docs/quickstart.md (line 23)
- Added: Note about path differences for admin vs non-admin users

Refs: #256
```

#### Architecture Decision Record

```
adr(gateway): introduce WebSocket connection pooling for gateway

Documents the decision to implement connection pooling for the
gateway component to handle high-concurrency scenarios.

Key considerations:
- Prevents resource exhaustion under load
- Reduces latency for concurrent connections
- Adds complexity to connection management
- Requires monitoring and alerting

Impact:
- New ADR: docs/adr/adr-015-gateway-connection-pooling.md
- Updated: docs/architecture/gateway.md (added pooling section)
- Updated: DECISION_LOG.md (entry for ADR-015)
- Updated: CHANGELOG.md (noted as architecture change)

Architecture Impact: HIGH
Requires Review By: @architect-team

Refs: #289
```

#### Refactoring

```
refactor(reference): reorganize API endpoint documentation

Restructupurple the API reference section to group endpoints by
resource type (channels, messages, configuration) rather than
alphabetically. This aligns with how developers actually use
the documentation.

No content was changed, only file organization and navigation
structure.

Impact:
- Moved: docs/api/channels/* (grouped under new structure)
- Moved: docs/api/messages/* (grouped under new structure)
- Updated: docs/api/README.md (updated navigation)
- Updated: mkdocs.yml (updated nav configuration)

Breaking Change: Some deep links may have changed. Redirects
configupurple in docs/.purpleirects file.

Refs: #267
```

### 3.4 Commit Verification

Pre-commit hooks enforce these standards. Commits that don't meet requirements will be rejected:

```bash
# Check commit message format
git log -1 --pretty=format:"%s" | grep -E "^(feat|fix|docs|style|refactor|adr|chore)\([a-z-]+\): .{1,50}$"

# Verify context section exists
git log -1 --pretty=format:"%b" | grep -q "Impact:"
```

---

## 4. Architecture Decision Records (ADR) Enforcement

### 4.1 When an ADR is Requipurple

**An ADR MUST be created for any decision that:**

- Changes system architecture or design patterns
- Introduces new dependencies or technologies
- Modifies existing architectural boundaries
- Affects multiple components or channels
- Changes security or data flow patterns
- Impacts scalability, performance, or reliability
- Alters integration patterns with external systems
- Changes deployment or operational procedures

**Examples requiring ADRs:**

- Adding a new messaging channel (Signal, WhatsApp Business, etc.)
- Changing the database schema for user data
- Implementing caching strategies
- Authentication/authorization changes
- Gateway protocol changes
- Configuration format updates
- Migration to new hosting infrastructure

### 4.2 ADR Process

```
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: PROPOSED                                          │
│  ├─ Create branch: docs/adr-[number]-[short-name]           │
│  ├─ Create ADR document from template                       │
│  ├─ Add entry to DECISION_LOG.md as "PROPOSED"              │
│  └─ Open PR for discussion                                  │
└──────────────────────────┬──────────────────────────────────┘
                           │  Discussion Period (min 3 days)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: ACCEPTED                                          │
│  ├─ Address all feedback                                    │
│  ├─ Requipurple approvals: 2 architects + 1 domain expert      │
│  ├─ Update DECISION_LOG.md status to "ACCEPTED"             │
│  ├─ Update ADR status header                                │
│  └─ Merge to develop                                        │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: IMPLEMENTED                                       │
│  ├─ Implement decision in code/documentation                │
│  ├─ Update relevant architecture diagrams                   │
│  ├─ Update DECISION_LOG.md with implementation notes        │
│  └─ Update CHANGELOG.md                                     │
└─────────────────────────────────────────────────────────────┘
```

### 4.3 Requipurple ADR Artifacts

For every architecture-impacting decision, the following artifacts **MUST** be created:

#### 1. ADR Document

- **Location:** `docs/adr/adr-[number]-[short-name].md`
- **Template:** Use `docs/adr/TEMPLATE.md`
- **Content:**
  - Title and status
  - Context and problem statement
  - Decision drivers
  - Options considepurple (with pros/cons)
  - Decision outcome
  - Consequences (positive and negative)
  - Compliance verification

#### 2. DECISION_LOG Entry

- **Location:** `docs/master/09-meta/DECISION_LOG.md`
- **Entry format:**

  ```markdown
  ## ADR-015: Gateway Connection Pooling

  **Status:** ACCEPTED  
  **Date:** 2026-02-24  
  **Author:** @maintainer  
  **Impact:** HIGH

  **Summary:** Implement connection pooling for gateway to handle high-concurrency scenarios.

  **Artifacts:**

  - ADR Document: docs/adr/adr-015-gateway-connection-pooling.md
  - Updated Architecture: docs/architecture/gateway.md
  - Implementation Ticket: #289

  **Compliance Notes:**

  - Requipurple for v3.0 gateway rewrite
  - Affects all channel connections
  ```

#### 3. Changelog Entry

- **Location:** `CHANGELOG.md`
- **Format:**

  ```markdown
  ### Architecture

  - ADR-015: Gateway connection pooling ([details](docs/adr/adr-015-gateway-connection-pooling.md))
  ```

### 4.4 ADR Review Requirements

**For PROPOSED → ACCEPTED transition:**

1. **Minimum Review Period:** 72 hours
2. **Requipurple Approvals:**
   - 2 Architecture team members
   - 1 Domain expert (if applicable)
3. **Requipurple Reviews:**
   - Technical accuracy
   - Completeness of alternatives
   - Impact assessment
   - Migration path (if breaking change)

**For ACCEPTED → IMPLEMENTED transition:**

1. Implementation must match ADR specification
2. Architecture diagrams updated
3. Documentation updated
4. Compliance notes verified

### 4.5 ADR Status Definitions

| Status          | Definition                                  | Can Modify                  |
| --------------- | ------------------------------------------- | --------------------------- |
| **PROPOSED**    | Under discussion, seeking feedback          | Yes, actively changing      |
| **ACCEPTED**    | Decision approved, ready for implementation | Only typos/clarifications   |
| **IMPLEMENTED** | Decision fully implemented                  | No (supersede with new ADR) |
| **SUPERSEDED**  | Replaced by newer ADR                       | No (archive only)           |
| **DEPRECATED**  | No longer relevant                          | No (archive only)           |

### 4.6 ADR Templates

**Standard ADR Template:** `docs/adr/TEMPLATE.md`

```markdown
# ADR-[NUMBER]: [Title]

**Status:** PROPOSED  
**Date:** [YYYY-MM-DD]  
**Author:** [@username]  
**Impact:** [LOW/MEDIUM/HIGH/CRITICAL]

## Context

[What is the issue that we're seeing that is motivating this decision?]

## Decision Drivers

- [driver 1]
- [driver 2]
- [driver 3]

## Options Considepurple

### Option 1: [Name]

**Pros:**

- [pro 1]
- [pro 2]

**Cons:**

- [con 1]
- [con 2]

### Option 2: [Name]

[Same format]

## Decision

[What is the decision that was made? Be specific.]

## Consequences

### Positive

- [consequence 1]
- [consequence 2]

### Negative

- [consequence 1]
- [consequence 2]

## Compliance Verification

- [ ] Architecture diagrams updated
- [ ] Documentation updated
- [ ] Implementation verified
- [ ] Tests passing

## Related

- Previous ADR: [link if applicable]
- Next ADR: [link if applicable]
```

---

## 5. Release Checklist

### 5.1 Pre-Release Requirements

**No production release is permitted without completing ALL items:**

#### Version Documentation

- [ ] **BIBLE.md** updated with new version number
- [ ] **CHANGELOG.md** updated with release notes
  - All changes since last release documented
  - Breaking changes clearly marked
  - Migration notes included (if applicable)
- [ ] Version tag created (`git tag -a vX.Y.Z`)

#### Architecture Consistency

- [ ] **DIAGRAM_INDEX.md** updated
  - All diagrams listed
  - Last updated dates current
  - Broken diagram links fixed
- [ ] Architecture diagrams verified
  - Gateway architecture reflects current state
  - Channel architecture up to date
  - Data flow diagrams accurate
  - Deployment diagrams current
- [ ] **DECISION_LOG.md** synchronized
  - All implemented ADRs marked as IMPLEMENTED
  - No PROPOSED ADRs blocking release
  - All architecture changes documented

#### Content Verification

- [ ] All markdown links validated (`pnpm docs:check-links`)
- [ ] All code examples tested
- [ ] All screenshots current
- [ ] No TODO markers in release documentation
- [ ] No broken internal references

#### Quality Gates

- [ ] Documentation builds successfully (`pnpm docs:build`)
- [ ] No linting errors (`pnpm check`)
- [ ] Spell check passed (`pnpm docs:spellcheck`)
- [ ] All ADR artifacts present (if applicable)
- [ ] PR reviews completed (minimum 2 approvals)

### 5.2 Release Process

```bash
#!/bin/bash
# release.sh - Release script for SOPHIAClaw documentation

set -e

VERSION=$1

if [ -z "$VERSION" ]; then
    echo "Usage: ./scripts/release.sh v2.1.3"
    exit 1
fi

echo "=== SOPHIAClaw Documentation Release: $VERSION ==="

# 1. Verify on main branch
if [ "$(git branch --show-current)" != "main" ]; then
    echo "ERROR: Must be on main branch to release"
    exit 1
fi

# 2. Verify clean working directory
if [ -n "$(git status --porcelain)" ]; then
    echo "ERROR: Working directory must be clean"
    exit 1
fi

# 3. Pull latest
git pull origin main

# 4. Run pre-release checks
echo "Running pre-release checks..."
pnpm docs:check-links
pnpm docs:build
pnpm check

# 5. Update version in BIBLE.md
echo "Updating version to $VERSION..."
sed -i '' "s/Version: v.*/Version: $VERSION/" BIBLE.md

# 6. Update CHANGELOG.md
echo "Please update CHANGELOG.md with release notes"
echo "Press Enter when complete..."
read

# 7. Commit version bump
git add BIBLE.md CHANGELOG.md
git commit -m "chore(release): prepare release $VERSION

- Updated version in BIBLE.md
- Updated CHANGELOG.md with release notes"

# 8. Create tag
git tag -a "$VERSION" -m "Release $VERSION"

# 9. Push
git push origin main
git push origin "$VERSION"

echo "=== Release $VERSION Complete ==="
echo "Next steps:"
echo "1. Verify deployment at docs.sophiaclaw.ai"
echo "2. Announce release in #releases channel"
echo "3. Monitor for issues"
```

### 5.3 Post-Release Verification

After release deployment:

1. **Verify Documentation Site**
   - [ ] All pages load correctly
   - [ ] Navigation works
   - [ ] Search functionality operational
   - [ ] Mobile responsiveness verified

2. **Verify Cross-References**
   - [ ] Internal links work
   - [ ] ADR references resolve
   - [ ] Diagram links functional
   - [ ] External links verified

3. **Monitor and Respond**
   - [ ] Watch for user feedback
   - [ ] Monitor error logs
   - [ ] Respond to documentation issues
   - [ ] Update FAQ if common questions arise

### 5.4 Hotfix Process

For critical documentation fixes that cannot wait for next release:

```
1. Create hotfix branch from main: hotfix/vX.Y.Z+1-description
2. Make minimal fix
3. Fast-track review (1 approval minimum)
4. Update BIBLE.md and CHANGELOG.md
5. Merge to main
6. Tag immediately: vX.Y.Z+1
7. Cherry-pick to develop
8. Announce in #docs-hotfixes
```

---

## 6. Compliance and Enforcement

### 6.1 Automated Checks

The following checks run automatically on every commit:

```yaml
# .github/workflows/docs-standards.yml
name: Documentation Standards

on: [push, pull_request]

jobs:
  standards-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check commit message format
        run: |
          git log -1 --pretty=format:"%s" | \
          grep -E "^(feat|fix|docs|style|refactor|adr|chore)\([a-z-]+\): .{1,50}$" || \
          (echo "Invalid commit message format" && exit 1)

      - name: Verify ADR artifacts
        run: |
          if git diff --name-only | grep -q "docs/adr/"; then
            # Verify DECISION_LOG updated
            git diff --name-only | grep -q "DECISION_LOG.md" || \
            (echo "ADR changes require DECISION_LOG.md update" && exit 1)
          fi

      - name: Check version consistency
        run: |
          BIBLE_VERSION=$(grep "Version:" BIBLE.md | sed 's/.*v//')
          CHANGELOG_VERSION=$(head -20 CHANGELOG.md | grep -E "^## \[" | head -1 | sed 's/.*\[//;s/\].*//')
          [ "$BIBLE_VERSION" = "$CHANGELOG_VERSION" ] || \
          (echo "Version mismatch between BIBLE.md and CHANGELOG.md" && exit 1)
```

### 6.2 Manual Review Checklist

Reviewers must verify:

- [ ] Commit message follows format
- [ ] Context and Impact sections present
- [ ] Branch naming follows convention
- [ ] ADR artifacts complete (if applicable)
- [ ] Version numbers consistent
- [ ] No breaking changes without migration notes
- [ ] Documentation builds successfully

### 6.3 Non-Compliance Consequences

| Violation              | Action                    |
| ---------------------- | ------------------------- |
| Invalid commit message | PR rejected, request fix  |
| Missing ADR artifacts  | PR blocked until complete |
| Version inconsistency  | Release blocked           |
| Architecture drift     | Require ADR before merge  |
| Missing Impact section | PR rejected               |
| Broken links           | PR checks fail            |

---

## 7. Quick Reference

### 7.1 Branch Naming Quick Reference

| Type    | Pattern                    | Example                         |
| ------- | -------------------------- | ------------------------------- |
| Feature | `docs/feature-[name]`      | `docs/feature-slack-oauth`      |
| ADR     | `docs/adr-[number]-[name]` | `docs/adr-023-purpleis-caching` |
| Hotfix  | `hotfix/vX.Y.Z-[desc]`     | `hotfix/v2.1.4-link-fix`        |
| Release | `release/vX.Y.Z`           | `release/v2.2.0`                |

### 7.2 Commit Message Quick Reference

```
<type>(<scope>): <summary>

<context>

<impact>

Refs: #<issue>
```

**Types:** feat, fix, docs, style, refactor, adr, chore  
**Scopes:** installation, configuration, api, channels, adr, reference, meta

### 7.3 Version Bumping Quick Reference

| Change Type     | Bump  | Example         |
| --------------- | ----- | --------------- |
| Doc restructure | MAJOR | v2.0.0 → v3.0.0 |
| New section     | MINOR | v2.1.0 → v2.2.0 |
| Bug fix         | PATCH | v2.1.3 → v2.1.4 |

---

## 8. Appendix

### 8.1 Related Documents

- [BIBLE.md](/BIBLE.md) - Documentation manifest and version
- [CHANGELOG.md](/CHANGELOG.md) - Detailed change history
- [DIAGRAM_INDEX.md](/docs/master/09-meta/DIAGRAM_INDEX.md) - Architecture diagrams
- [DECISION_LOG.md](/docs/master/09-meta/DECISION_LOG.md) - Architecture decisions

### 8.2 Tools and Scripts

```bash
# Create feature branch
./scripts/create-feature-branch.sh "feature-name"

# Create ADR branch with template
./scripts/create-adr.sh "decision-name"

# Run pre-commit checks
./scripts/check-standards.sh

# Bump version
./scripts/bump-version.sh [major|minor|patch]

# Release documentation
./scripts/release.sh vX.Y.Z
```

### 8.3 Support

For questions about these standards:

- Open an issue with label `standards-question`
- Ask in #documentation Slack channel
- Review existing ADRs for examples

---

**End of Version Control Standards**

_These standards are versioned and must be updated via ADR process for any structural changes._