FTC Versioning Guardrail

STOP: Do Not Manually Change Version Numbers!

This repository uses an automated release process. Contributors should NEVER manually change version numbers in any file.

Files You Should NOT Edit (Version Fields)

The Correct Workflow

For Contributors

1. Make your changes to the skill (SKILL.md, scripts, etc.)

2. Add changelog entries to ## [Unreleased] section in CHANGELOG.md:

   ## [Unreleased]
   
   ### Added
   - New calibration script for pod offset calculation
   
   ### Fixed
   - Corrected coordinate transformation formula
   

3. Use the update-skill command to help generate entries:

   /update-skill <skill-name>
   

4. Submit PR to the develop branch

5. Done! – Versions are bumped automatically during the release process

For Maintainers (Release Process)

1. Go to GitHub Actions
2. Run “Prepare Release” workflow
3. Script automatically:
   • Parses changelog categories (Added → MINOR, Fixed → PATCH, etc.)
   • Calculates new version numbers
   • Updates all three version locations atomically
   • Creates release PR

Why This Matters

Deterministic Versioning

Version bumps are calculated from changelog categories:

Consistency Guarantee

The release script ensures:

• All three version locations match
• Changelog is properly formatted
• Release notes are generated
• Git tags are created

Avoiding Merge Conflicts

Manual version bumps cause:

• Merge conflicts when multiple PRs touch versions
• Inconsistency between files
• Confusion about which version is correct

Exception: New Skills (1.0.0)

When creating a new skill with /create-skill, the version IS set to 1.0.0. This is the only time a version is “manually” set, and it’s done by the create-skill command.

New skills should:

• Start at version 1.0.0
• Have this in plugin.json, SKILL.md, and marketplace.json
• Have initial 1.0.0 entry in CHANGELOG.md

If You’re Tempted to Bump a Version

Ask yourself:

1. Did I add entries to the ## [Unreleased] section? (Do this instead!)
2. Am I running the release process? (Only maintainers do this)
3. Is this a new skill? (Let create-skill handle it)

If none of these apply, you probably shouldn’t be changing version numbers.

Commands Reference

None of these commands change version numbers after initial creation.

See Also

• RELEASES.md – Full release process documentation
• .github/scripts/prepare-release.sh – The release automation script
• .github/workflows/prepare-release.yml – The release workflow