📦 Semantic Versioning Decision Tree

An interactive tool to help you determine the correct semantic version bump for your project. Choose between MAJOR, MINOR, or PATCH version updates using a guided decision tree.

🎯 What is Semantic Versioning?

Semantic Versioning (SemVer) uses a three-part version number: MAJOR.MINOR.PATCH (e.g., 1.2.3)

• MAJOR (X.0.0): Breaking changes that are incompatible with previous versions
• MINOR (X.Y.0): New features added in a backwards-compatible manner
• PATCH (X.Y.Z): Bug fixes and internal improvements without API changes

Learn more at semver.org

🚀 Quick Start

Option 1: Interactive Web Interface

The web interface is automatically deployed to GitHub Pages. Access it here:

🌐 Live Demo

Or open docs/index.html locally in your browser:

open docs/index.html
# or
firefox docs/index.html

The web interface is automatically deployed when you push changes to the docs/ directory using GitHub Actions.

Option 2: Bash Command Line

Make the script executable and run it:

chmod +x semver.sh
./semver.sh

Answer each question with Y (Yes) or N (No), and the tool will determine your next version.

📋 How It Works

The decision tree guides you through these questions:

1. Have you made ANY changes to your project?

   • No → PATCH (no version bump)
   • Yes → Continue

2. Have you made breaking changes? (non-backwards compatible)

   • Yes → MAJOR ✅
   • No → Continue

3. Have you added NEW features? (backwards compatible)

   • Yes → MINOR ✅
   • No → Continue

4. Have you only fixed bugs or improved performance?

   • Yes → PATCH ✅
   • No → Continue

5. Are your changes INTERNAL ONLY? (tests, docs, build process)

   • Yes → PATCH ✅
   • No → Continue

6. Are you unsure?

   • Yes → MINOR (safer default) ✅
   • No → PATCH (minimal changes)

📁 Files Included

.
├── LICENSE             # MIT License
├── README.md           # This file
├── semver.sh           # Bash command-line tool
└── docs/
    └── index.html      # Interactive web interface (deployed via GitHub Pages)

💻 Requirements

For Web Interface

• Any modern web browser (Chrome, Firefox, Safari, Edge, etc.)
• No installation or dependencies needed
• Access via GitHub Pages or local file

For Bash CLI Tool

• Bash shell (v3.0+)
• Linux, macOS, or Windows (with WSL/Git Bash)

🔧 Setup & Deployment

GitHub Pages Setup

This project uses GitHub Actions to automatically deploy the web interface from the docs/ directory:

1. Enable GitHub Pages in your repository settings:

   • Go to Settings → Pages
   • Select "Deploy from a branch"
   • Choose main branch and /docs folder
   • Save

2. GitHub Actions automatically deploys your changes when you push to the repository

3. Access your live demo at: https://ahmedukamel.github.io/Semantic-Versioning-Decision-Tree/

The web interface will be updated automatically with each push to the repository!

🎮 Usage Examples

Web Interface

1. Open index.html in your browser
2. Answer Yes/No questions
3. Get your version recommendation with detailed explanation
4. Click "Start Over" to analyze another change

Bash Interface

$ ./semver.sh

╔════════════════════════════════════════╗
║     📦 Semantic Versioning Helper      ║
╚════════════════════════════════════════╝

Path: Start
Progress: [░░░░░░░░░░░░░░░░░░░░] 0%

Have you made ANY changes to your project?
[Y/N]: Y

# ... continue answering questions ...

╔════════════════════════════════════════╗
║      🟢 MINOR VERSION BUMP             ║
╚════════════════════════════════════════╝

Decision: MINOR Version Bump

You've added new backwards-compatible features.
Increment the second number: X.Y → X.(Y+1).0

Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)

🆘 Command Line Options

./semver.sh -h          # Show help
./semver.sh --help      # Show help
./semver.sh -v          # Show version
./semver.sh --version   # Show version

📖 Decision Guide

When to Use MAJOR (🔴)

• Removing or renaming public API methods
• Changing function signatures
• Modifying data structures in incompatible ways
• Breaking changes to configuration format
• Example: 1.0.0 → 2.0.0

When to Use MINOR (🟢)

• Adding new features
• Adding new public API methods
• Deprecating features (with warnings)
• Performance improvements without API changes
• Example: 1.2.0 → 1.3.0

When to Use PATCH (🔵)

• Fixing bugs
• Security patches
• Minor performance improvements
• Updating dependencies for internal use
• Documentation updates
• Example: 1.2.3 → 1.2.4

🔄 Version Bump Examples

Change	Current	New
Bug fix	1.2.3	1.2.4
New feature	1.2.3	1.3.0
Breaking change	1.2.3	2.0.0
Multiple fixes	1.2.3	1.2.5
Multiple features	1.2.3	1.4.0

💡 Best Practices

• Always reset MINOR and PATCH to 0 when bumping MAJOR

  • 1.5.3 → 2.0.0 (not 2.5.3)

• Reset PATCH to 0 when bumping MINOR

  • 1.2.5 → 1.3.0 (not 1.3.5)

• Use pre-release versions for testing before release

  • 2.0.0-beta.1, 2.0.0-rc.1

• Document breaking changes clearly in your changelog

  • Help users understand what needs to update

• When in doubt, choose MINOR over MAJOR

  • It's more conservative and safer for users

🤝 Contributing

Found an issue or want to improve this tool? Feel free to submit issues or pull requests!

📝 License

This project is open source and available under the MIT License.

🔗 Resources

• Semantic Versioning Official Guide
• npm Version Management
• Python Versioning

---

Made with ❤️ by Ahmed Kamel

© 2025 Ahmed Kamel. All rights reserved.

Licensed under the MIT License - see LICENSE file for details.