Skip to main content
Version: v2

Version scheme

Vortex supports CalVer and SemVer version numbering schemes to fit different project needs.

During installation, you can choose between Calendar Versioning (CalVer), Semantic Versioning (SemVer), or a custom scheme.

Calendar versioning (CalVer)​

Format: YY.M.Z (e.g., 25.1.0, 25.11.1)

  • YY = Short year (no leading zeroes)
  • M = Short month (no leading zeroes)
  • Z = Hotfix/patch version (no leading zeroes)

Why CalVer​

  • Release frequency transparency: When you have multiple releases per month, dates make it easy to identify when a release happened
  • Intuitive tracking: Stakeholders can immediately understand "this is from January 2025" without memorizing version numbers
  • Natural progression: No ambiguity about major vs minor changes - the order is chronological
  • Stakeholder communication: Easier to reference for non-technical audiences ("our Q1 2025 release")

Examples​

  • ✅ Correct: 25.1.0, 25.11.1, 25.1.10, 25.10.1
  • ❌ Incorrect: 25.0.0 (no month 0), 2025.1.1 (full year), 25.01.0 (leading zero), 01.1.0 (leading zero in year)

Learn more: CalVer.org

Semantic versioning (SemVer)​

Format: X.Y.Z (e.g., 1.0.0, 2.3.5)

  • X = Major release version (no leading zeroes)
  • Y = Minor release version (no leading zeroes)
  • Z = Hotfix/patch version (no leading zeroes)

Why SemVer​

  • Breaking change communication: Major version bump signals incompatible API changes
  • Dependency management: Package managers can enforce compatible version ranges
  • Developer expectations: Well-understood convention in the development community
  • Predictable upgrades: Minor versions add functionality, patches fix bugs

Examples​

  • ✅ Correct: 0.1.0, 1.0.0, 1.0.1, 1.0.10
  • ❌ Incorrect: 0.1 (missing patch), 1 (missing minor and patch), 1.0.01 (leading zero)

Learn more: SemVer.org

Other​

Choose "Other" if you have a custom versioning scheme or don't want to commit to CalVer or SemVer. This option removes both versioning templates from your documentation, allowing you to define your own approach.

Configuration​

Your project's version scheme is configured once during installation and stored in .env:

VORTEX_RELEASE_VERSION_SCHEME=calver  # or semver, or other

Release notes publishing​

Vortex provides a GitHub Actions workflow to automate release notes drafting:

  • Draft release notes are automatically updated when commits are pushed to the develop branch
  • The next version number is proposed per your scheme: computed from the current date for CalVer, and resolved by release-drafter (minor increment by default) for SemVer
  • The workflow reads the scheme from the VORTEX_RELEASE_VERSION_SCHEME repository variable, defaulting to calver when the variable is unset - set it in your repository settings to match your project's scheme, since the .env value does not drive this workflow
  • Release notes accumulate changes until the release is finalized
  • On release finish, you can use the draft to publish the final release notes