Skip to main content

Releasing

Software releases are a critical part of the development lifecycle. A well-structured release process ensures code quality, minimizes deployment risks, and maintains clear communication across teams.

A typical release process consists of several key components:

  1. Release Manager - A person or team responsible for coordinating and executing releases
  2. Release Flow - The sequence of environments and steps code goes through from development to production
  3. Versioning Workflow - The branching strategy that governs how code moves through environments (GitFlow being the most common)
  4. Version Scheme - The numbering system used to identify releases (CalVer, SemVer, or custom)
  5. Release Documentation - Runsheets, checklists, and procedures stored in accessible locations
  6. Automated Deployment - CI/CD pipelines that handle the technical deployment process

Vortex provides comprehensive support for all these components, with sensible defaults and integration points for popular hosting platforms.

Release flow​

Projects typically follow a three-tier environment strategy with clear directional flows:

  • Development - Latest development code, not yet released. May be unstable, but CI tests should pass.
  • Stage - Pre-production environment. Mirrors production as closely as possible. Used for final release testing.
  • Production - Live customer-facing application. Stable and reliable. Source of truth for data.
Environment Agreement

The specific environment setup (dev/stage/production) should be agreed upon within your team and documented in your project. Some teams may use additional environments (e.g., UAT, pre-prod) or different naming conventions.

Code goes "up" (from lower to higher environments) while database goes "down" (from higher to lower environments).

This means that the production database is the primary source of truth - it's what code is applied to. When performing a release, you are applying a new version of code to a database within a specific environment.

To ensure that code changes work correctly with real data structures, the following process is followed in lower environments:

  1. Database is copied from a higher environment to a lower one (e.g., production → stage → development)
  2. Code is deployed to that environment to be tested against the copied database
  3. Testing is performed to ensure everything works correctly
tip

CI pipelines also use a copy of the production database (refreshed daily) to run all tests, ensuring code changes work with real data structures.

You would use a Versioning Workflow (like GitFlow) to manage how code moves across releases using the Version Scheme (like CalVer or SemVer).

You would document your release procedures in Release Documentation (like docs/releasing.md) and create a release runsheet to guide release managers through the release process.

Finally, the actual deployment to production is handled via Automated Deployment where, based on your hosting provider, the deployment process is fully automated.

GitFlow versioning workflow​

git-flow is a versioning workflow that allows you to maintain clean separation between development and production code.

It allows you to have a stable development branch (develop) and a production-ready branch (main), while providing dedicated branches for feature development, release preparation, and hotfixes.

Branch structure​

  • develop - Development branch where features are integrated
  • main - Production-ready code, always stable and tagged with releases
  • feature/* - Individual feature development branches
  • release/* - Release preparation branches (e.g., release/25.1.0)
  • hotfix/* - Emergency fixes for production (e.g., hotfix/25.1.1)
production branch

Most hosting providers support deploying specific git tags directly. In this case, no separate production branch is needed - you simply tag releases on main and deploy those tags.

Some hosting providers (like Lagoon) require a git branch to deploy from, so tag-based deployments are not supported. In this case, you must create a production branch and sync code from main to production after each release.

While it's possible to automate copying main to production on tag creation via CI/CD, this automation was conceptually avoided to prevent accidental deployments to production without human oversight.

Release operations​

Below are the typical steps to perform a release using git-flow. See cheat sheet for a quick reference on git-flow commands.

  1. Start Release

    git flow release start X.Y.Z

    Creates a release/X.Y.Z branch from develop. It is recommended to push the branch to remote.

  2. Release Preparation

    • Final bug fixes
    • Documentation updates
    • Release notes preparation

  3. Finish Release

    git flow release finish X.Y.Z
    • Merges release branch to main
    • Tags the release
    • Merges back to develop
    • Deletes the release branch

  4. Deploy to Production

    • Tag-based hosting: Deploy the tag directly

    • Branch-based hosting (e.g., Lagoon): Manually sync to production branch

      git push origin main:production

Expected release outcome​

A successful release should meet these criteria:

  1. Release branch exists as release/X.Y.Z in GitHub repository
  2. Release tag exists as X.Y.Z in GitHub repository
  3. The HEAD of the main branch has X.Y.Z tag
  4. The hash of the HEAD of the main branch exists in the develop branch
    • This ensures everything pushed to main exists in develop
    • Important if main had any hotfixes not yet merged to develop
  5. There are no open PRs in GitHub related to the release

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" vs memorizing version numbers
  • Natural progression: No ambiguity about major vs minor changes - just the chronological order
  • Marketing alignment: Easier to communicate to non-technical audiences ("our Q1 2025 release")

Examples​

  • ✅ Correct: 25.1.0, 25.11.1, 25.1.10, 25.10.1, 9.12.0
  • ❌ 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​

For CalVer and SemVer projects, 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
  • Next version is calculated based on your version scheme
  • Release notes accumulate changes until the release is finalized
  • On release finish, you can use the draft to publish the final release notes

Production deployment process​

Once code is finalized and pushed, the deployment process to production is technically identical to deploying to other environments and is fully automated.

For Acquia and Lagoon hosting, Vortex integrates directly with their deployment systems to ensure smooth releases.

For other hosting providers, you can integrate the provision steps into your hosting deployment configuration if it supports post-deployment hooks or custom scripts.

See Provisioning documentation to learn more about what provisioning steps are performed during deployments.

Documentation​

docs/releasing.md​

Your project includes a docs/releasing.md file that serves as the canonical release documentation for your team. This file contains:

  • Version scheme summary - Which versioning system your project uses (CalVer, SemVer, or Other)
  • GitFlow instructions - Step-by-step guide for your specific git-flow setup
  • Release procedures - Custom workflows specific to your project

You can extend this file with:

  • Detailed release procedures - A comprehensive outline of what actions to take during releases:
    • Steps to create and finish releases
    • Steps to deploy to production
    • Steps to rollback
    • Steps to verify releases
  • Release run template - A detailed checklist of who does what and when during releases. This would be cloned into a separate runsheet for each release.

Monitoring​

New relic integration​

Vortex provides integration with New Relic for release tracking and monitoring.

Deployment Markers: When configured, Vortex automatically creates deployment markers in New Relic when releases are deployed to your environments. These markers help correlate performance changes, errors, and other metrics with specific releases.

Benefits:

  • Visualize before/after release performance
  • Correlate errors with specific deployments
  • Track deployment frequency
  • Monitor release impact in real-time

➡️ See Workflows > Notifications > New Relic

Best practices​

  1. Always use release branches - Never release directly from develop or feature branches
  2. Backup before release - Ensure you have recent backups of code and data
  3. Document your process - Keep docs/releasing.md updated with team conventions
  4. Automate everything possible - Leverage Vortex's automation capabilities
  5. Test in Stage first - Always validate releases in a production-like environment
  6. Communicate releases - Notify stakeholders before, during, and after releases
  7. Monitor post-release - Watch metrics and logs for issues after deployment
  8. Have a rollback plan - Document and test your rollback procedures
  9. Use consistent versioning - Stick to your chosen version scheme