Release naming conventions

Release branches and tags

Release branches

Release branches for modern Drupal projects follow the format {major}.x or {major}.{minor}.x. Drupal 8 and earlier used {API compatibility}-{major}.x. Examples are:

Release tags

Release tags for modern Drupal projects follow the format {major}.{minor}.{patch}. Drupal 8 and earlier used {API compatibility}-{major}.{minor}. Both formats 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.

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.

With semantic versioning, composer.json and core_version_requirement are used to define a release’s requirement for Drupal core.

Stable releases and pre-releases

Tags ending in -alpha, -beta, and -rc, followed by a number, are pre-releases. Read more about the distinctions between Alpha, Beta and RC. 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, 8.x-1.0-rc1 is valid for making a release, but the following are NOT:

• 8.x-1.0-release1 wrong word
• 8.x-1.0-rc doesn’t end in a digit
• 8.x-1.0-ALPHA1 uppercase

alpha: Most reported errors are resolved, but there may still be serious outstanding known issues, including security issues. Project is not thoroughly tested, so there may also be many unknown bugs. There is a README.txt/README.md that documents the project and its API (if any). The API and DB schema may be unstable, but all changes to these are reported in the release notes, and hook_update_N is implemented to preserve data through schema changes, but no other upgrade/update path. Not suitable for production sites. Target audience is developers who want to participate in testing, debugging and development of the project.

beta: 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 it is an upgrade or update of a project, an upgrade/update path should be offered, and 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. Target audience is developers who want to participate in testing, debugging and development of the project, and developers of other projects that interfaces the project. Not generally suitable for production sites, but may be used on some production sites if the site administrator knows the project well, and knows how to handle any outstanding issues.

rc: A release candidate should only be created when all reported critical bug type issues are fixed in the project's issue queue. This tag should only be used when 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, but 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.

If you prefix a branch name with a Drupal.org issue number, like 1234-improve-situation, it will be associated with that issue.

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 7.x-1.x, 8.x-1.x, or 1.x as your main development branch (see below).