Release naming conventions

Release branches and tags

Starting a new project? Create a 1.x branch, make it your default branch, and tag your first stable release 1.0.0. Your project's version number is independent of Drupal core's; see Drupal core compatibility. Projects that still use version numbers like 8.x-1.x are covered in Legacy 8.x-* versioning.

Release branches

Release branches for most modern Drupal projects follow the format {major}.x. Use one branch per major version: 1.x for all 1.* releases, 2.x for all 2.* releases, and so on. Examples are:

Release branches can also follow the format {major}.{minor}.x. Drupal core uses these, and so do contrib projects that keep fixing bugs in an older minor version while new features go into the next one. Most contrib projects don’t need them.

For example, this allows you to use 1.x as main for all releases in the 1.* series. Once you’ve made tagged releases in the 1.1.* series, if you are back-porting to 1.0.*, then you can also make the 1.0.x branch for those commits, if needed.

Release tags

Release tags for Drupal projects follow the format {major}.{minor}.{patch}. They can have a pre-release suffix, like {major}.{minor}.{patch}-(alpha|beta|rc){N}, see Stable releases and pre-releases below for details. Examples are:

Releases are packaged soon after a release is created, or a new commit is pushed to a dev release’s branch. Usually within 10 minutes, up to an hour delay can happen if the packaging queue is busy.

While it is possible to use a zero as first number (for example 0.1.0) the convention is to start from 1, for example 1.0.0.

Drupal core compatibility

Your project’s version number is independent of Drupal core’s version number. For example, a 2.x branch is version 2 of your project, not a version for Drupal 2.

composer.json and core_version_requirement are used to define a release’s requirement for Drupal core. Since most releases are likely to be compatible with multiple versions of Drupal core, one release can support several core major versions.

Stable releases and pre-releases

Tags ending in -alpha, -beta, and -rc, followed by a number, are pre-releases. Tags which end in a number, without the -…N suffix, are stable releases.

All pre-release tags must end with a number. The first is numbered 1 (as in …-alpha1), the next 2 (as in …-alpha2), and so on. When you make a release with the next stability, reset the number following the previous example. …-beta1 would be next.

For example, 1.0.0-rc1 is valid for making a release, but the following are not:

• 1.0.0-release1 uses a wrong pre-release type
• 1.0.0-rc doesn’t end with a digit
• 1.0.0-ALPHA1 uses uppercase character

The supported pre-release types are the following.

alpha

Target audience is developers who want to participate in testing, debugging and development of the project.

Most reported errors are resolved. There may still be serious outstanding known issues, including security issues.

Project is not thoroughly tested, so there may also be many unknown bugs.

The API and DB schema may be unstable but all changes to these are reported in the release notes. Also, hook_update_N() is implemented to preserve data through schema changes, but no other upgrade/update path.

There is a README.txt/README.md that documents the project and its API (if any).

beta

Target audience is the same as the alpha phase plus developers of other projects that interface with the project. May be used on some production sites if the site administrator knows the project well, and knows how to handle any outstanding issues.

All critical data loss and security bugs are resolved.

If the module offers an API, it should be considered frozen, so that those using the API can start upgrading their projects.

If this is an upgrade or update of a project, an upgrade/update path should be offered. It should be possible for existing users to upgrade/update to the new version without loss of data.

All documentation should be up to date.

rc

A release candidate should only be created when all reported critical bugs are fixed. At this stage, the developer believes that the project is ready for use on a production site.

There is no official best practice for how long a project should be a release candidate before creating a official .0 release. It is suggested that it should be out for at least a month with status set to "needs review".

If something (e.g. a new critical bug is reported) makes it necessary to create a new release during this period, a new release candidate should be created. and this should remain for at least a month with status set to "needs review".

Feature branches

In a distributed version control system workflow, like Git, it’s common to spin off separate branches for features, bug fixes, and anything else you want to try out. You are free to name your branches whatever you like for your day-to-day work. awesome-new-feature, experimental-redesign, performance-bugfix are all acceptable branch names.

Git’s default master branch should be avoided and no downloadable releases can be tied to that branch. Master branch cleanup information here. Use a release branch like 1.x as your main development branch.

Legacy 8.x-* versioning

Drupal 8 and earlier used {API compatibility}-{major}.x for release branches and {API compatibility}-{major}.{minor} for release tags. Many projects still have releases in this format, and they work with current versions of Drupal core when their core_version_requirement allows it. Examples are:

Transitioning from 8.x-* to semantic versioning

Since Drupal 8, projects can be compatible with any range of Drupal core versions. So 8.x-* releases and releases using semantic versioning occupy the same space for version numbers. Put another way, a 8.x-1.0 release is effectively the same as 1.0.0

When your project switches to using semantic versioning, you must increment your major version. For example, if the latest release is 8.x-3.5, your next stable release will be 4.0.0

(The converse is also restricted, once 4.0.0 is released, you can’t release 8.x-4.0 or 8.x-5.0)

8.x-* projects can be compatible with Drupal 9, so you don’t need to switch right away if you aren’t ready to start a new major version release series.

Most versions of Drupal 8 are not compatible with semantic versioning. If your project supports Drupal 8.8.3 or lower, don’t switch to semantic versioning.

9.x-* and later releases can not be made. Since most releases made now are likely to be compatible with multiple versions of Drupal core, the API compatibility prefixes don’t make sense to keep. Use semantic versioning for any release only compatible with Drupal 9 or higher.