Skip to main content

Release

Versioning Strategy​

Vortex uses Semantic Versioning for releases: MAJOR.MINOR.PATCH

Semantic version (MAJOR.MINOR.PATCH)​

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

Version examples​

  • 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 creating a new release, determine the version based on the changes:

  1. Bump MAJOR when making incompatible breaking changes:

    • Removing features or configuration options
    • Changing default behavior that breaks existing projects
    • Updating to new major versions of services or dependencies that require migration

  2. Bump MINOR when adding functionality in a backward compatible manner:

    • Adding new optional features
    • Adding new scripts or commands
    • Enhancing existing features without breaking changes

  3. Bump PATCH when making backward compatible bug fixes:

    • Fixing bugs or errors
    • Security patches
    • Documentation updates
    • Minor improvements that don't change functionality

Branch strategy​

  • 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, ...)
  • 1.x - a maintenance branch for a superseded major version, behind main (for example 1.x once 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 installer's bare /install URL both follow it, while the per-major docs and /v{N}/install pins are always published.

When main advances to a new major version:

  1. The upcoming major's branch (for example 2.x) is merged into main
  2. The superseded major continues on its own branch (for example 1.x) for maintenance
note

Vortex uses GitHub Flow with the main branch always containing 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 both are created, their order is fixed: tag the tooling first, then tag Vortex.

  • drevops/vortex-tooling - the shipped tooling package, split from .vortex/tooling/. Its branches are mirrored to the package repository automatically, but tags are created manually as part of cutting a release.
  • Vortex - the template itself.

The following rules apply to every release:

  1. Vortex is always tagged. A release always creates the Vortex tag, whether or not the tooling changed.
  2. The tooling is always referenced by a tag. The drevops/vortex-tooling requirement in Vortex's root composer.json must point at a published tag - never a branch or a development alias.
  3. The tooling is tagged before Vortex when it changed. When .vortex/tooling/ has changed since the previous Vortex release, create and publish the new drevops/vortex-tooling tag before tagging Vortex.
  4. Vortex caps its tooling requirement at the tagged version. When the tooling is tagged for a release, require that freshly tagged drevops/vortex-tooling version in root composer.json with a tilde constraint (for example ~1.3.0). This makes the freshly tagged version the upper boundary of the requirement at the minor level: later patch releases within the same minor are still accepted, but the requirement cannot float onto a newer minor that was never published with the release.

Release Process​

Follow the steps below to release a new version of the Vortex:

  1. Run renovate bot locally to update all dependencies outside of the schedule:
renovate --schedule= --force-cli=true drevops/vortex
  1. Update container images to the latest versions and check that @see links are working.
    • 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 it must not be copied verbatim.
  2. Update PHP version in composer.json for config.platform.
  3. Update PHP version in phpcs.xml for testVersion.
  4. Update PHP version in phpstan.neon for phpVersion. Run php -r "echo PHP_VERSION_ID . PHP_EOL;" in the container to get the current PHP version.
  5. Tag drevops/vortex-tooling first when it changed. If .vortex/tooling/ changed since the previous release, create and publish a new drevops/vortex-tooling tag now - before the Vortex tag (see Tagging).
  6. Increment minor version of all packages in composer.json. Run composer update -W && composer bump. When the tooling was tagged in the previous step, require that freshly tagged drevops/vortex-tooling version with a tilde constraint (for example ~1.3.0, see Tagging); otherwise keep the existing tag constraint.
  7. Update minor version of dependencies in theme's package.json.
  8. Increment the cache version in .circleci/config.yml and .github/workflows/build-test-deploy.yml.
  9. Updated documentation with cd .vortex && ahoy update-docs.
  10. Update installer video with cd .vortex && ahoy update-videos installer.
  11. Tag the Vortex release and publish the GitHub release using the template below. Vortex is always tagged; when the tooling changed, its tag is created first (see Tagging).
## [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, behaviour changes (but not fully breaking)]

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

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

---

### 🎛 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
- [ ] 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`.
- [ ] Updated minor version of all packages in `composer.json`.
- [ ] Tagged `drevops/vortex-tooling` before the Vortex tag when the tooling changed, and pinned the freshly tagged version as the upper boundary in `composer.json`.
- [ ] Updated minor version of dependencies in theme's `package.json`.
- [ ] Update `drevops/ci-runner` to the latest version in `.circleci/config.yml` and `.github/workflows/build-test-deploy.yml`.
- [ ] Incremented the cache version in `.circleci/config.yml` and `.github/workflows/build-test-deploy.yml`.
- [ ] Updated documentation.
- [ ] Tagged the Vortex release.

---

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

@AlexSkrypnyk, @renovate[bot] and [renovate[bot]](https://github.com/apps/renovate)