Skip to main content
Version: v1

Release

This page is for the maintainers who cut Vortex releases. It covers the version numbers, the branches and the tags, and it walks through the checklist that ends with a published release. A project built from Vortex has its own release flow; see Releasing.

Versioning strategy​

Vortex uses Semantic Versioning for releases, in the form MAJOR.MINOR.PATCH.

Semantic version (MAJOR.MINOR.PATCH)​

Each part of the version marks a kind of change:

  • MAJOR: Breaking changes that require migration or significant updates
  • MINOR: New features, backward compatible
  • PATCH: Bug fixes, backward compatible

Version examples​

These versions show how the parts change:

  • 1.0.0 - First major release
  • 1.1.0 - New features added
  • 1.1.1 - Bug fix release
  • 2.0.0 - Breaking changes

Version numbering guidelines​

For a new release, pick the part to bump from the changes it contains:

  • For incompatible breaking changes, bump MAJOR:
    • Removing features or configuration options
    • Changing default behavior that breaks existing projects
    • Updating to new major versions of services or dependencies that require migration
  • For features added in a backward compatible manner, bump MINOR:
    • Adding new optional features
    • Adding new scripts or commands
    • Enhancing existing features without breaking changes
  • For backward compatible bug fixes, bump PATCH:
    • Fixing bugs or errors
    • Security patches
    • Documentation updates
    • Minor improvements that leave a feature's behavior unchanged

Branch strategy​

The repository uses these branches:

  • main - the current major version under active development, the major that the VORTEX_CURRENT_MAJOR repository variable names
  • 2.x - a development branch for an upcoming major version, ahead of main (later majors follow the same pattern: 3.x, 4.x and later)
  • 1.x - a maintenance branch for a superseded major version, behind main (1.x takes this role after main moves to major version 2)

To promote a new major version on the published site, set the VORTEX_CURRENT_MAJOR repository variable to its number. It's a GitHub Actions variable on the drevops/vortex repository, under Settings > Secrets and variables > Actions, on the Variables tab. The documentation default and the installer's bare /install URL both follow it, while the per-major docs and the /v{N}/install pins are always published.

The workflows read the variable only when they run. The next Vortex - Release docs run applies a change to the live site and /install. To publish straight away, run that workflow by hand.

When main advances to a new major version, the branches change like this:

  • The upcoming major's branch, for example 2.x, merges into main.
  • The superseded major continues on its own branch, for example 1.x, for maintenance.
note

Vortex uses GitHub Flow, with the main branch always holding the current major version.

Consumer projects created from Vortex should continue to use Git Flow.

Tag a release​

A release always produces a Vortex tag. When the tooling changed, it also produces a drevops/vortex-tooling tag, and the order is fixed: tag the tooling first, then tag Vortex.

The 2 tags belong to these parts:

  • drevops/vortex-tooling - the shipped tooling package, split from .vortex/tooling/. A workflow mirrors its branches to the package repository automatically, but you create its tags by hand as part of cutting a release.
  • Vortex - the template itself.

The following rules apply to every release:

  • A release always creates the Vortex tag, with or without tooling changes.
  • The drevops/vortex-tooling requirement in Vortex's root composer.json must always point at a published tag, never a branch or a development alias.
  • When .vortex/tooling/ has changed since the previous Vortex release, create and publish the new drevops/vortex-tooling tag before tagging Vortex.
  • Vortex limits its tooling requirement to the tagged version's minor. Require the freshly tagged drevops/vortex-tooling version in root composer.json with a tilde constraint, for example ~1.3.0. The tagged version is the lower bound, and the next minor is the exclusive upper bound. Later patch releases within the same minor still match, but the requirement can't float onto a newer minor that wasn't published with the release.

Release process​

The release checklist takes the template from its previous release to a published tag. Follow it in order, because later steps regenerate files from the changes that earlier steps make.

Before you begin​

Make sure you have the following:

  • Push access to drevops/vortex, and to drevops/vortex-tooling when the tooling changed
  • The Renovate CLI, with a GitHub token that can write to drevops/vortex
  • Ahoy, Git, Composer, Node.js (with npm and Yarn) and curl on your PATH, because the steps run them on your machine
  • PHP 8.3 or later on your machine, for Composer and the PHP scripts that the steps run
  • Docker, for the cli container, ahoy update-docs, the snapshot run and the video recordings
  • The .vortex/ dependencies, installed with ahoy install from .vortex/
  • The recording tools that Documentation > Documentation videos lists

Cut the release​

To release a new version of Vortex:

  1. To update all dependencies outside of the schedule, run Renovate locally:

    renovate --schedule= --force-cli=true drevops/vortex

  2. Update the container images to their latest versions.

    • After bumping the uselagoon/solr-9-drupal image, update solr.luceneMatchVersion in .docker/config/solr/config-set/solrcore.properties to match the Lucene version bundled in that image, which the lucene-core-*.jar filename inside the image shows. The value in search_api_solr's jump-start config-set lags the image, so don't copy it verbatim.

  3. Check that the @see links are working.

  4. Get the PHP version and the PHP version ID that the cli container runs:

    docker compose run --rm cli php -r "echo PHP_VERSION . PHP_EOL;"
    docker compose run --rm cli php -r "echo PHP_VERSION_ID . PHP_EOL;"

    The first command prints the version, for example 8.4.25, and the second command prints its ID, for example 80425.

  5. In composer.json, set config.platform.php to the PHP version.

  6. In phpcs.xml, set testVersion to the major and minor PHP version, for example 8.4.

  7. In phpstan.neon, set phpVersion to the PHP version ID.

  8. If .vortex/tooling/ changed since the previous release, create and publish a new drevops/vortex-tooling tag now, before the Vortex tag (see Tag a release). To check for changes, run git log PREVIOUS_VERSION..HEAD -- .vortex/tooling, where PREVIOUS_VERSION is the previous Vortex tag. The command prints nothing when the tooling didn't change.

  9. Update all packages and raise their constraints in composer.json to the installed versions: run composer update -W && composer bump.

  10. If you tagged the tooling in step 8, set its version in the 4 places that pin it:

    • The require constraint in root composer.json, as a tilde constraint, for example ~1.3.0 (see Tag a release)
    • The versions entry of the path repository in root composer.json
    • The versions entry in scripts/vortex-tooling.sh
    • The versions entry in .vortex/tests/phpunit/Traits/SutTrait.php

    Then search the repository for the previous tooling version, to catch a pin that this list misses. Without a new tooling tag, keep the existing tooling constraint.

  11. In web/themes/custom/your_site_theme/, update the minor versions of the dependencies in package.json. Use npm for this step, because the theme keeps a package-lock.json.

  12. Update drevops/ci-runner to its latest version, both the tag and the digest, in every file that pins it by hand:

    • .circleci/config.yml
    • .github/workflows/build-test-deploy.yml
    • .github/workflows/audit.yml
    • .github/workflows/vortex-test-common.yml

  13. Update the database cache version in .circleci/config.yml and .github/workflows/build-test-deploy.yml. The version follows the tag of the uselagoon/* container images, with a v prefix:

    • If this release bumped those images, set it to their new tag, for example v26.9.0 for uselagoon/php-8.4-cli-drupal:26.9.0.
    • Otherwise, increment its last segment, for example from v26.8.0 to v26.8.1, to force a cache reset.

  14. Run cd .vortex && ahoy lint-ci-fix to regenerate .circleci/vortex-test-common.yml and .github/workflows/vortex-test-didi.yml, which carry copies of the runner image and the cache version from .circleci/config.yml and .github/workflows/build-test-deploy.yml.

  15. Update the documentation with cd .vortex && ahoy update-docs.

  16. Commit the changes.

  17. Regenerate the installer snapshots with cd .vortex && ahoy update-snapshots. If the Docker Compose fixtures in .vortex/tests/phpunit/Fixtures/ change, the command stops before the installer step: commit them and run it again. It commits the installer fixtures itself.

  18. Re-record the demo videos with cd .vortex && ahoy update-videos.

  19. Commit the recorded videos under .vortex/docs/static/img/.

  20. Tag the Vortex release and push the tag. The push runs the Vortex - Release docs workflow, which publishes the documentation and the installer.

  21. Publish the GitHub release, with the following template as its body:

## [VERSION] - [SHORT TITLE]

[Very short summary, 1-3 sentences. E.g. "This release updates the base template to Drupal X.Y, improves the installer UX, and expands documentation for local dev."]

---

## 🔍 Highlights

- [1-3 top-level items that matter most to users]
- [Optional: link to detailed docs if relevant]

---

## 💥 Breaking changes

- [Describe any breaking changes and upgrade steps]
- [If none] None.

---

## What's new since [PREVIOUS_VERSION]

### 🌀 Template

- ✨ **New**
  - [New features or major additions in the project template]

- 🛠 **Changed**
  - [Improvements, refactors, behavior changes (but not fully breaking)]

- 🐞 **Fixed**
  - [Bug fixes]

- ⬆️ **Updated**
  - [Dependency bumps, version updates, etc.]

---

### 🧰 Tooling

- [Changes to the `drevops/vortex-tooling` scripts package, with the tag released with this version]
- [If none] None.

---

### 🎛 Installer

- ✨ **New**
  - [New installer options, flows, flags]

- 🛠 **Changed**
  - [Improved UX, default choices, messages]

- 🐞 **Fixed**
  - [Installer bugs, edge cases]

---

### 📖 Documentation

- ✨ **New**
  - [New pages, guides, sections]

- 🛠 **Changed**
  - [Rewrites, restructuring, clarifications]

- 🐞 **Fixed**
  - [Typos, incorrect examples, broken links]

---

## 📋 Release checklist

- [ ] Updated all dependencies outside of the schedule.
- [ ] Updated container images to the latest versions and checked that `@see` links are working.
- [ ] Updated PHP version in `composer.json` for `config.platform`.
- [ ] Updated PHP version in `phpcs.xml` for `testVersion`.
- [ ] Updated PHP version in `phpstan.neon` for `phpVersion`.
- [ ] Tagged `drevops/vortex-tooling` before the Vortex tag when the tooling changed, and required the freshly tagged version with a tilde constraint in `composer.json` so the requirement stays within that version's minor.
- [ ] Updated minor version of all packages in `composer.json`.
- [ ] Updated minor version of dependencies in theme's `package.json`.
- [ ] Updated `drevops/ci-runner` to the latest version in `.circleci/config.yml` and `.github/workflows/build-test-deploy.yml`.
- [ ] Incremented the database cache version in `.circleci/config.yml` and `.github/workflows/build-test-deploy.yml`.
- [ ] Updated documentation.
- [ ] Regenerated the installer snapshots.
- [ ] Re-recorded the demo videos.
- [ ] Tagged the Vortex release.

---

**Full Changelog**: https://github.com/drevops/vortex/compare/[PREVIOUS_VERSION]...[NEW_VERSION]

[CONTRIBUTORS]

Confirm that the release is live: the Vortex - Release docs workflow run for the tag succeeds, and the published installer reports the new version. To check the installer, run these commands:

curl -SsL https://www.vortextemplate.com/install > installer.php
php installer.php --version

The second command prints Vortex Installer followed by the tag, for example Vortex Installer 1.42.0.