quicknotes/.cursor/rules/rule-versioning-strategy.mdc

---
description: Standards for versioning Cursor rules as they evolve over time
globs: .cursor/rules/*.mdc
---
<rule>
filters:
  - type: file_extension
    pattern: "\\.mdc$"
  - type: file_path
    pattern: "^\\.cursor\\/rules\\/"

actions:
  - type: suggest
    message: |
      # Rule Versioning Strategy
      
      ## Version Format
      
      1. Use semantic versioning for rules:
         ```
         metadata:
           version: MAJOR.MINOR.PATCH
         ```
         - MAJOR: Breaking changes that require significant adjustments
         - MINOR: New features or guidance that's backward compatible
         - PATCH: Bug fixes, clarifications, or examples
      
      2. Version history section:
         ```
         version_history:
           - version: 1.2.0
             date: 2023-07-15
             changes:
               - Added guidance for new technology X
               - Updated examples for framework version Y
           - version: 1.1.1
             date: 2023-06-10
             changes:
               - Fixed incorrect example in section Z
         ```
      
      ## When to Version
      
      1. MAJOR version increment:
         - Changing fundamental principles or approaches
         - Removing previously required processes
         - Modifying the rule's core purpose
         - Restructuring sections in a non-backward compatible way
      
      2. MINOR version increment:
         - Adding new guidance or best practices
         - Expanding rule scope to new file types
         - Adding new sections
         - Enhancing examples
      
      3. PATCH version increment:
         - Correcting typos or grammar
         - Clarifying existing points
         - Fixing incorrect examples
         - Updating links or references
      
      ## Version Management Process
      
      1. Documentation:
         - Always include a changelog in the version_history section
         - Summarize changes in commit messages
         - Reference related issues or discussions
      
      2. Review and Approval:
         - Major versions require team review
         - Minor versions need at least one reviewer
         - Patch versions can be applied directly for urgent fixes
      
      3. Communication:
         - Announce major version changes to all team members
         - Document migration paths for breaking changes
         - Provide context for why changes were made
      
      ## Rule Deprecation
      
      1. Deprecation Process:
         - Mark rule as deprecated with reason:
           ```
           metadata:
             deprecated: true
             deprecation_reason: "Replaced by new-rule-name.mdc"
             removal_date: "2023-12-31"
           ```
         - Keep deprecated rules for at least 3 months
         - Reference replacement rules when applicable
      
      2. Archiving:
         - Move to .cursor/rules/archived/ directory
         - Retain version history
         - Document archival reason
      
      ## Compatibility Considerations
      
      1. Tool Compatibility:
         - Test rule changes with current tooling
         - Ensure rules work with target Cursor versions
         - Document minimum required tool versions
      
      2. Backward Compatibility:
         - Maintain backward compatibility when possible
         - Document migration steps when breaking
         - Support transition periods for major changes

metadata:
  priority: high
  version: 1.0
  version_history:
    - version: 1.0
      date: 2023-09-01
      changes:
        - Initial version of rule versioning strategy
</rule>

examples:
  - input: |
      # Bad: Rule with no version information
      ---
      description: Frontend styling guidelines
      globs: **/*.css
      ---
      <rule>
      # CSS Guidelines
      
      Use BEM naming conventions.
      </rule>
    output: |
      # Good: Properly versioned rule
      ---
      description: Frontend styling guidelines
      globs: **/*.css
      ---
      <rule>
      # CSS Guidelines
      
      Use BEM naming conventions.
      
      metadata:
        priority: medium
        version: 1.0
        version_history:
          - version: 1.0
            date: 2023-09-01
            changes:
              - Initial CSS guidelines
      </rule>
      
  - input: |
      # Bad: Rule update without version increment
      # Previous version:
      # metadata:
      #   version: 1.2.0
      
      # Updated rule with new section but same version
      ---
      description: API design standards
      globs: **/*.ts
      ---
      <rule>
      # API Design Standards
      
      ## REST Guidelines
      Use proper HTTP methods.
      
      ## GraphQL Guidelines (New section)
      Use fragments for reusable components.
      
      metadata:
        priority: high
        version: 1.2.0
      </rule>
    output: |
      # Good: Rule update with proper version increment
      ---
      description: API design standards
      globs: **/*.ts
      ---
      <rule>
      # API Design Standards
      
      ## REST Guidelines
      Use proper HTTP methods.
      
      ## GraphQL Guidelines
      Use fragments for reusable components.
      
      metadata:
        priority: high
        version: 1.3.0
        version_history:
          - version: 1.3.0
            date: 2023-09-15
            changes:
              - Added GraphQL guidelines section
          - version: 1.2.0
            date: 2023-08-10
            changes:
              - Updated REST guidelines with authentication best practices
      </rule>