Version: v2

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

When you create 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 don't change what a feature does

Branch strategy

The repository uses these branches:

main - the current major version under active development (1.x today)
2.x - a development branch for an upcoming major version, ahead of main (future majors follow the same pattern: 3.x, 4.x, and so on)
1.x - a maintenance branch for a superseded major version, behind main (for example 1.x after main holds 2.x)

Promoting a new major version is a single action: set the VORTEX_CURRENT_MAJOR repository variable to its number. The documentation default and the bare /install URL both follow it, while the per-major docs and the /v{N}/install pins are always published.

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 latest major version.

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

Tagging

A release always produces a Vortex tag, and also a drevops/vortex-tooling tag when the tooling changed. When you create both, their 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 pins its tooling requirement to the tagged version's minor. When you tag the tooling for a release, require that freshly tagged drevops/vortex-tooling version in root composer.json with a tilde constraint (for example ~2.0.0). The tagged version is the lower bound and the next minor is the exclusive upper bound. Later patch releases within the same minor are still accepted, but the requirement can't float onto a newer minor that was never published with the release.

Release process

The release checklist takes the template from its previous release to a published tag. Follow it in order: 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 PHP 8.3 or later on your machine
Docker, for the cli container, the snapshot run, and the video recording
The .vortex/ dependencies, installed with ahoy install from .vortex/

Cut the release

To release a new version of Vortex, follow these steps:

To update all dependencies outside of the schedule, run Renovate locally:
```
renovate --schedule= --force-cli=true drevops/vortex
```
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 (shown by the lucene-core-*.jar filename inside the image). The value in search_api_solr's jump-start config-set lags the image, so don't copy it verbatim.
Check that the @see links are working.

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 commands print the version and its ID, for example 8.4.27 and 80427.

In composer.json, set config.platform.php to the PHP version.
In phpcs.xml, set testVersion to the major and minor PHP version, for example 8.4.
In phpstan.neon, set phpVersion to the PHP version ID.
If .vortex/tooling/ changed since the previous release, create and publish a new drevops/vortex-tooling tag now, before the Vortex tag (see Tagging). 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.
Increment the minor version of all packages in composer.json: run composer update -W && composer bump.
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 ~2.0.0 (see Tagging)
- 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
Without a new tooling tag, keep the existing tag constraint.
In web/themes/custom/your_site_theme/, update the minor versions of the dependencies in package.json.
Align the CI runner PHP version with config.platform.php: the PHP image tags in .circleci/config.yml, and the php-version of the setup-php steps in the GitHub Actions workflows.
Increment the cache version in .circleci/config.yml and .github/workflows/build-test-deploy.yml.
Run cd .vortex && ahoy lint-ci-fix to regenerate .circleci/vortex-test-common.yml, which carries a copy of .circleci/config.yml.
Update the documentation with cd .vortex && ahoy update-docs.
Commit the changes.
Regenerate the CLI snapshots with cd .vortex && ahoy update-snapshots and commit the regenerated fixtures.
Update the install demo video with cd .vortex && ahoy update-videos cli-install and commit the output.
Tag the Vortex release. Pushing the tag runs the Vortex - Release docs workflow, which publishes the documentation and the CLI.
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 CLI 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.

---

### 🎛 CLI

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

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

- 🐞 **Fixed**
  - [CLI 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`.
- [ ] Aligned the CI runner PHP version with `config.platform` (the `cimg/php` tag in `.circleci/config.yml` and the `setup-php` `php-version` in the GitHub Actions workflows).
- [ ] Incremented the cache version in `.circleci/config.yml` and `.github/workflows/build-test-deploy.yml`.
- [ ] Updated documentation.
- [ ] Regenerated the CLI snapshots.
- [ ] Re-recorded the demo videos.
- [ ] Tagged the Vortex release.

---

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

[CONTRIBUTORS]

Versioning strategy​

Semantic version (MAJOR.MINOR.PATCH)​

Version examples​

Version numbering guidelines​

Branch strategy​

Tagging​

Release process​

Before you begin​

Cut the release​