docs: add versioning and archiving best practices guide #493
Conversation
Add comprehensive guide covering: - Silent data loss issue when multiple branches modify same requirements - Best practices for batch archiving workflow - Archive ordering strategies to prevent conflicts - CodeRabbit configuration recommendations - OPSX workflow as safer alternative - Roadmap for upcoming conflict resolution features Addresses common pain points teams encounter with parallel development and weekly batch archiving workflows.
📝 WalkthroughWalkthroughAdds a new documentation guide explaining OpenSpec versioning and archiving challenges, the OPSX AI-driven merging workflow, setup and usage instructions, workflow comparisons, examples, and remediation guidance for non-OPSX environments. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 🧹 Recent nitpick comments
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (7)📓 Common learnings📚 Learning: 2025-11-25T01:08:02.839ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:02.839ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
📚 Learning: 2025-11-25T01:08:19.004ZApplied to files:
🪛 markdownlint-cli2 (0.18.1)docs/versioning-and-archiving-guide.md9-9: Fenced code blocks should have a language specified (MD040, fenced-code-language) 34-34: Fenced code blocks should have a language specified (MD040, fenced-code-language) 57-57: Fenced code blocks should have a language specified (MD040, fenced-code-language) 73-73: Fenced code blocks should have a language specified (MD040, fenced-code-language) 103-103: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) 105-105: Fenced code blocks should have a language specified (MD040, fenced-code-language) 129-129: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) 131-131: Fenced code blocks should have a language specified (MD040, fenced-code-language) 155-155: Fenced code blocks should have a language specified (MD040, fenced-code-language) 185-185: Fenced code blocks should have a language specified (MD040, fenced-code-language) 199-199: Fenced code blocks should have a language specified (MD040, fenced-code-language) 209-209: Fenced code blocks should have a language specified (MD040, fenced-code-language) 249-249: Fenced code blocks should have a language specified (MD040, fenced-code-language) 278-278: Fenced code blocks should have a language specified (MD040, fenced-code-language) 293-293: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🔇 Additional comments (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/versioning-and-archiving-guide.md (1)
91-91: Consider using a heading instead of bold text.For better document structure and accessibility, convert the bold text to a level 3 heading.
📝 Proposed fix
-**Recommendation: Exclude spec files** +### Recommendation: Exclude spec files
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/versioning-and-archiving-guide.md
🧰 Additional context used
🧠 Learnings (10)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
docs/versioning-and-archiving-guide.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
docs/versioning-and-archiving-guide.md
🪛 markdownlint-cli2 (0.18.1)
docs/versioning-and-archiving-guide.md
7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
32-32: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
61-61: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
91-91: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
128-128: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
148-148: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
164-164: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
docs/versioning-and-archiving-guide.md (1)
194-195: Linked documentation files are present and accessible.Both referenced documentation files exist in the repository:
openspec-parallel-merge-plan.mdexists at the repository rootdocs/experimental-workflow.mdexists in the docs directoryThe relative links are correctly formed.
Significantly expanded the versioning/archiving guide to better address user concerns about parallel development conflicts: - Added TL;DR with jump link to solution - Expanded OPSX section from 8 lines to ~120 lines - Added step-by-step authentication conflict example - Added three-team concrete example showing all merge scenarios - Added two workflow options (Friday batch vs sync-as-you-go) - Added "What cases does this handle" section - Updated quick reference card to lead with OPSX - Restructured flow: Problem → OPSX Solution → Manual fallback - Moved manual practices to "If You Can't Use OPSX Yet" section The guide now clearly positions OPSX as the solution with actionable examples instead of being buried as a light mention.
Summary
Adds a comprehensive guide addressing the silent data loss issue when multiple feature branches modify the same requirements during batch archiving workflows.
This guide provides:
Context
This documentation responds to a user question about best practices for managing concurrent changes that touch the same specifications. The issue is documented in
openspec-parallel-merge-plan.mdbut wasn't easily discoverable for teams experiencing the problem.Target Audience
Teams experiencing or concerned about:
Changes
docs/versioning-and-archiving-guide.mdTest Plan
openspec-parallel-merge-plan.md🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.