Development Tools & Downloads

Get started with semantic versioning and conventional commits by downloading our pre-configured rule files for Cursor, GitHub Copilot, Claude Code, and Windsurf.

📥 Quick Downloads

AI Assistant Rules

<h3 className="text-xl font-bold mb-2">🌊 Windsurf Rules (.mdc)</h3>

<p className="text-muted-foreground mb-4">
  AI-enforced rules for Windsurf IDE with semantic versioning and conventional commits.
</p>
<span className="text-primary font-medium">Download windsurf-rules.mdc →</span>

GitHub Actions Workflows

<h3 className="text-xl font-bold mb-2">📖 Complete Setup Guide</h3>

<p className="text-muted-foreground mb-4">
  Comprehensive guide for setting up automated branch promotions.
</p>
<span className="text-primary font-medium">Download setup guide →</span>

🎯 Cursor Rules (.mdc)

What's Included

✅ Conventional Commits enforcement - Automatic validation of commit message format
✅ Semantic Versioning rules - Clear guidelines for MAJOR, MINOR, and PATCH bumps
✅ Git tagging protocols - Best practices for annotated tags
✅ Code style preferences - TypeScript, React, and API conventions
✅ Release workflow guidance - Step-by-step release process
✅ Common scenarios - Examples for hotfixes, features, and breaking changes

Installation (Cursor)

1. Download the file:

   • Click the download button above
   • Or download cursor-rules.mdc directly

2. Create the Cursor rules directory:

   mkdir -p /path/to/your/project/.cursor/rules
   

3. Place the file in .cursor/rules/:

   mv ~/Downloads/cursor-rules.mdc /path/to/your/project/.cursor/rules/80-versioning.mdc
   

4. Restart Cursor:

   • Close and reopen Cursor
   • The AI will now enforce these rules automatically

5. Verify it's working:

   • Try writing a commit message
   • Cursor should suggest Conventional Commits format

Note: Cursor uses .mdc (Markdown Cursor) files in the .cursor/rules/ directory. The filename prefix (e.g., 80-) determines loading order.

What Cursor Will Do

Once installed, Cursor will:

• ✅ Format your commit messages automatically
• ✅ Suggest appropriate version bumps
• ✅ Guide you through the release process
• ✅ Enforce code style preferences
• ✅ Catch common versioning mistakes

🤖 GitHub Copilot Instructions

What's Included

✅ Commit message templates - Copilot suggests properly formatted messages
✅ Versioning explanations - Context-aware version bump guidance
✅ Tag creation commands - Proper git tag commands with annotations
✅ Code style guidance - TypeScript and React best practices
✅ Release workflow steps - Complete release process guidance
✅ Troubleshooting help - Common issues and solutions

Installation (GitHub Copilot)

Method 1: Repository-Level Instructions

1. Download the file:

   • Click the download button above
   • Or download copilot-instructions.md directly

2. Place in your repository:

   mkdir -p .github
   mv ~/Downloads/copilot-instructions.md .github/copilot-instructions.md
   

3. Commit the file:

   git add .github/copilot-instructions.md
   git commit -m "docs: add GitHub Copilot instructions"
   git push
   

4. Enable in VS Code (if needed):

   • Open Settings (Cmd/Ctrl + ,)
   • Search for "copilot instructions"
   • Enable "Code Generation: Use Instruction Files"

Method 2: Personal Instructions (Your Account Only)

1. In VS Code, open Command Palette (Cmd/Ctrl + Shift + P)
2. Type "GitHub Copilot: Edit Personal Instructions"
3. Paste the contents of copilot-instructions.md
4. Save the file

What Copilot Will Do

Once installed, GitHub Copilot will:

• ✅ Suggest properly formatted commit messages
• ✅ Explain version bumps when asked
• ✅ Generate git tag commands with proper annotations
• ✅ Guide you through release workflows
• ✅ Help troubleshoot versioning issues

🧠 Claude Code Rules (.mdc)

What's Included

✅ Conventional Commits enforcement - Automatic validation of commit message format
✅ Semantic Versioning rules - Clear guidelines for MAJOR, MINOR, and PATCH bumps
✅ Git tagging protocols - Best practices for annotated tags
✅ Interactive guidance - Context-aware suggestions for terminal and IDE
✅ Release workflow - Complete release process with examples
✅ Troubleshooting - Common issues and solutions

Installation (Claude Code - Terminal)

1. Download the file:

   • Click the download button above
   • Or download claude-code-rules.mdc directly

2. Create a project-specific instructions file:

   # Create .claude directory in your project
   mkdir -p /path/to/your/project/.claude
   mv ~/Downloads/claude-code-rules.mdc /path/to/your/project/.claude/rules.mdc
   

3. Or use global Claude settings:

   • Open Claude Code settings
   • Navigate to "Custom Instructions"
   • Paste the contents of the file

4. Verify it's working:

   • Open terminal in your project
   • Ask Claude: "Help me write a commit message"
   • Claude should suggest Conventional Commits format

Installation (Claude Code - IDE Integration)

If using Claude Code with VS Code or other IDEs:

1. Download the file
2. Place in .claude/ directory (similar to Cursor)
3. Reference in your IDE settings

What Claude Code Will Do

Once installed, Claude Code will:

• ✅ Format your commit messages interactively
• ✅ Explain version bumps with reasoning
• ✅ Generate proper git tag commands
• ✅ Guide you through complex releases
• ✅ Provide troubleshooting for versioning issues
• ✅ Suggest fixes for malformed commits

🌊 Windsurf Rules (.mdc)

What's Included

✅ Conventional Commits validation - Real-time commit message checking
✅ Semantic Versioning guidance - MAJOR, MINOR, PATCH decision tree
✅ Annotated tagging - Proper git tag creation with metadata
✅ Code style rules - TypeScript, React, and API conventions
✅ Release automation - Step-by-step release workflow
✅ Best practices - Hotfixes, features, and breaking changes

Installation (Windsurf)

1. Download the file:

   • Click the download button above
   • Or download windsurf-rules.mdc directly

2. Create the Windsurf rules directory:

   mkdir -p /path/to/your/project/.windsurf/rules
   

3. Place the file in .windsurf/rules/:

   mv ~/Downloads/windsurf-rules.mdc /path/to/your/project/.windsurf/rules/80-versioning.mdc
   

4. Restart Windsurf:

   • Close and reopen Windsurf IDE
   • The AI will now enforce these rules automatically

5. Verify it's working:

   • Try creating a commit
   • Windsurf should validate format automatically

Note: Windsurf uses .mdc files in the .windsurf/rules/ directory. The filename prefix (e.g., 80-) determines loading order (same as Cursor).

What Windsurf Will Do

Once installed, Windsurf will:

• ✅ Validate commit messages in real-time
• ✅ Suggest appropriate version bumps
• ✅ Guide you through release tagging
• ✅ Enforce code style preferences
• ✅ Catch versioning mistakes before push
• ✅ Provide interactive release assistance

⚙️ GitHub Actions: Auto-Promote Staging

What's Included

✅ Automatic PR creation - When develop CI passes, staging PR appears
✅ Commit analysis - Counts features, fixes, and breaking changes
✅ Smart type detection - Determines correct semantic commit type
✅ Pre-merge checklist - Comprehensive validation before merge
✅ Security hardened - SHA-pinned actions, minimal permissions
✅ Zero manual work - Fully automated workflow

Installation (GitHub Actions)

1. Download the workflow file:

   • Click the download button above
   • Or download auto-promote-staging.yml directly

2. Create workflows directory:

   mkdir -p .github/workflows
   

3. Place the file:

   mv ~/Downloads/auto-promote-staging.yml .github/workflows/auto-promote-staging.yml
   

4. Enable workflow permissions:

   • Go to: Settings → Actions → General
   • Scroll to: Workflow permissions
   • Select: "Read and write permissions"
   • Click: Save

5. Commit and push:

   git add .github/workflows/auto-promote-staging.yml
   git commit -m "feat: add automated staging promotion workflow"
   git push origin develop
   

6. Test it:

   • Wait for CI to pass on develop
   • Watch your first automated PR appear! 🎉

What It Does

Once installed, the workflow will:

• ✅ Trigger after CI passes on develop branch
• ✅ Check if staging branch needs updates
• ✅ Analyze all commits being promoted
• ✅ Determine highest-impact commit type (breaking > feat > fix > chore)
• ✅ Create PR with proper semantic type in title
• ✅ Include commit summary and pre-merge checklist
• ✅ Assign labels for easy filtering

Related: Complete blog post on automated branch promotions

🚀 GitHub Actions: Auto-Promote Production

What's Included

✅ Semantic version prediction - Calculates next version automatically
✅ Breaking change detection - Identifies MAJOR version bumps
✅ Commit type analysis - Determines MINOR vs PATCH bumps
✅ Edge case handling - Pre-release, build metadata, invalid formats
✅ Production checklist - Security and deployment validation
✅ Audit trail - Clear history of production releases

Installation (GitHub Actions)

1. Download the workflow file:

   • Click the download button above
   • Or download auto-promote-production.yml directly

2. Place in workflows directory:

   mv ~/Downloads/auto-promote-production.yml .github/workflows/auto-promote-production.yml
   

3. Commit and push:

   git add .github/workflows/auto-promote-production.yml
   git commit -m "feat: add automated production promotion workflow"
   git push origin staging
   

4. Test it:

   • Wait for CI to pass on staging
   • Review the automatically created production PR
   • Check the version prediction is correct

What It Does

Once installed, the workflow will:

• ✅ Trigger after CI passes on staging branch
• ✅ Fetch current production version tag
• ✅ Analyze all commits since last release
• ✅ Calculate next semantic version (MAJOR/MINOR/PATCH)
• ✅ Detect breaking changes automatically
• ✅ Create production PR with version in title
• ✅ Include comprehensive pre-deployment checklist

Version calculation rules:

• Breaking changes (feat!, BREAKING CHANGE) → MAJOR bump
• New features (feat:) → MINOR bump
• Bug fixes (fix:) → PATCH bump
• Other changes → No bump

🔢 Semantic Version Calculator

What's Included

✅ Standalone bash script - Use in any CI/CD system
✅ Conventional Commits parsing - Analyzes commit history
✅ Edge case handling - Pre-release, build metadata, etc.
✅ Well-documented - Clear comments and usage examples
✅ Battle-tested - Used in production by ReleaseRay
✅ Zero dependencies - Just bash and git

Installation (Bash Script)

1. Download the script:

   • Click the download button above
   • Or download calculate-version.sh directly

2. Make it executable:

   chmod +x calculate-version.sh
   

3. Use standalone:

   # Calculate next version from commits
   ./calculate-version.sh v1.2.3 HEAD
   
   # Output: v1.3.0 (if new features found)
   

4. Or use in GitHub Actions:

   - name: Calculate next version
     id: version
     run: |
       chmod +x calculate-version.sh
       NEXT_VERSION=$(./calculate-version.sh ${{ env.CURRENT_VERSION }} HEAD)
       echo "next_version=$NEXT_VERSION" >> $GITHUB_OUTPUT
   

5. Or use in other CI systems:

   # GitLab CI, Jenkins, CircleCI, etc.
   NEXT_VERSION=$(./calculate-version.sh $(git describe --tags --abbrev=0) HEAD)
   echo "Next version: $NEXT_VERSION"
   

What It Does

The script will:

• ✅ Parse current version tag
• ✅ Analyze commits between current version and target
• ✅ Detect breaking changes (MAJOR bump)
• ✅ Count features (MINOR bump)
• ✅ Count fixes (PATCH bump)
• ✅ Handle pre-release versions
• ✅ Handle build metadata
• ✅ Output next semantic version

Example usage:

# Current version: v1.2.3
# Commits since v1.2.3:
#   - feat: add OAuth2
#   - fix: resolve bug
#   - docs: update guide

./calculate-version.sh v1.2.3 HEAD
# Output: v1.3.0 (MINOR bump due to feat:)

📖 Automated Branch Promotions Guide

What's Included

✅ Complete setup instructions - Step-by-step for all workflows
✅ Security best practices - SHA-pinning, minimal permissions
✅ Troubleshooting section - Common issues and solutions
✅ Customization examples - Slack notifications, custom labels, etc.
✅ Real-world examples - Before/after comparisons
✅ Integration guide - Works with semantic-release, ReleaseRay

Contents

The guide covers:

1. Prerequisites - Branch structure, commit format, branch protection
2. Installation - Detailed setup for both workflows
3. Configuration - Customizing for your team's needs
4. Semantic versioning - How version prediction works
5. Security - GitHub Actions security best practices
6. Troubleshooting - Common problems and fixes
7. Advanced usage - Slack notifications, custom logic, etc.
8. Integration - Using with semantic-release and ReleaseRay

Download

Download automated-branch-promotions-guide.md

Or read the complete blog post: Automate Branch Promotions with GitHub Actions

🚀 Quick Start After Installation

1. Test Commit Message Formatting

Try committing with a simple message:

git add .
git commit -m "updated auth"

With rules installed:

• Cursor: Will suggest proper format like feat(auth): add OAuth2 support
• Copilot: Will offer to rewrite in Conventional Commits format

2. Create Your First Tag

Ask your AI assistant:

"Help me create a tag for my project. I added two new features and fixed a bug."

Expected guidance:

# MINOR bump (new features)
git tag -a v1.6.0 -m "Release v1.6.0: Add new features"
git push origin v1.6.0

3. Generate Release Notes

1. Go to ReleaseRay
2. Connect your repository
3. Select tag range (e.g., v1.5.0 → v1.6.0)
4. Generate persona-specific release notes
5. Publish to GitHub, Intercom, or your changelog

📚 What's the Difference?

Which should I use?

• Using Cursor? → Download cursor-rules.mdc
• Using VS Code + Copilot? → Download copilot-instructions.md
• Using Claude Code (terminal or IDE)? → Download claude-code-rules.mdc
• Using Windsurf? → Download windsurf-rules.mdc
• Using multiple tools? → Download all files! They complement each other and won't conflict.

🔧 Advanced Configuration

Customizing Rules

Both files are plain text and fully customizable:

1. Download the file
2. Open in your editor
3. Modify rules to match your team's workflow
4. Save and commit to your repository

Combining with Other Tools

These rules work great with:

• commitlint - Enforce commit format in CI/CD
• husky - Git hooks for pre-commit validation
• semantic-release - Automated versioning and releases
• ReleaseRay - AI-powered release note generation

See our Versioning Guide for complete setup instructions.

📖 Documentation

Full Guides

• Complete Versioning Guide - Comprehensive guide to semantic versioning, conventional commits, and automation
• Semantic Versioning - Official SemVer specification
• Conventional Commits - Commit message convention

Tool Documentation

• Cursor Rules - Official Cursor documentation
• GitHub Copilot Instructions - Official GitHub documentation

💡 Examples

Commit Message Examples

Before (unclear):

git commit -m "updated stuff"
git commit -m "fix"
git commit -m "WIP"

After (clear):

git commit -m "feat(auth): add OAuth2 authentication"
git commit -m "fix(api): handle null user responses"
git commit -m "docs: update setup instructions"

Tagging Examples

Before (lightweight):

git tag v1.2.3

After (annotated):

git tag -a v1.2.3 -m "Release v1.2.3: Add user management

- Add user profile page
- Add user settings
- Fix user avatar upload bug"

🤝 Community

Share Your Customizations

Have you customized these rules for your team? Share them with the community!

• Submit a PR to our examples repository
• Share on Twitter with #ReleaseRay
• Write a blog post about your workflow

Get Help

• Documentation: Versioning Guide
• Issues: Report problems on GitHub
• Support: Email support@releaseray.com

🎉 Ready to Get Started?

Need automated release notes? Try ReleaseRay to generate AI-powered release notes from your git tags.