Version numbers, policies and which version you should use

Which Drupal version should I run?

It is recommended that you run the most current stable release. This can always be found at the Drupal Project page. However, if there are no compelling features in the latest version, a contrib module that is important to you isn't ready or you don't have time, there is no need to rush your upgrade as long as security updates are available for the version you are running.

The current stable release is Drupal 6.0. The next version will be Drupal 7. It is in early development. If previous patterns continue, Drupal 7 will likely be released in early 2009. Drupal 5 still supported, the current version is 5.7.

If you are just starting your site you need to do a needs assessment (both functionality and launch date requirements) in advance of deciding whether to begin building with Drupal 6 or Drupal 5. There may be some contributed modules that would be key to your design that have not yet been ported to Drupal 6.

When is the next release?

Per the Open Source tradition, when it's ready. When sufficient testing of fixes of bug reports is complete. More attention is given to a rapid release of security issues. The more people involved in fixing and testing reported issues, the faster a release is likely to come out.

How do I know which version of Drupal I'm running?

If it's available, go to Administer >> Logs >> Status report. This will list your version number if you have Drupal 5.0 or later.

Failing that, look for a file called CHANGELOG.txt in the root of your Drupal directory and open it up to find the version you are running.

If CHANGELOG.txt is missing, you can also check in system.module for a line at the top like:

define('VERSION', '5.5');

If this is present, it will tell you which version of 5.x you are running. If not, you have a version earlier than 4.7.0.

Is my version of Drupal supported?

Supported versions for security patches and availability for download are the current stable release and one version previous. Running unsupported versions may expose you to unknown security risks and you are strongly urged to remain updated to a supported version and sign up with the security notification list.

What about upgrading and backwards compatibility?

For more details read this overview of the Drupal's philosophy on backwards compatibility.

What do Drupal's version numbers mean?

In Drupal 4.7.x and previous, the first two numbers indicated the Drupal version number, while the last indicated a "point" or bug-fix release with a specific "patch level". For example, "4.7.3" means "the third bug-fix release (patch level 3) of the 4.7 version of Drupal."

This was frequently confusing for people who expected 4.7.x to be a minor update of 4.6.x, when in fact this was far from the case. Different versions of Drupal often break API compatibility with one another, and require contributed modules to be upgraded.

Starting with Drupal 5.x, the "5" indicates the major version of Drupal, and the .x is the bug-fix release or patch level. That means that 5.0, 5.1, and 5.2 all have the same underlying structure and modules for 5.x are all compatible with each other. However, modules written for Drupal 6.x will not work with 5.x and vice-versa.

Development snapshots

A release with "-dev" at the end of the version indicates a development snapshot from the end of a CVS branch (as opposed to an official release from a CVS tag). These snapshots, by their nature, include changing code. It is therefore hard to know exactly what revisions of each file they contain, even if it is a snapshot of a stable branch where only bug fixes and security enhancements are being made (such as the 4.7.x-dev snapshot release of Drupal core). This makes them more difficult to debug and the should generally be avoided for production sites. Development snapshots also use "x" for the patch level to further indicate the variable nature of the code they contain. Both Drupal core and the contributions can have development snapshots.

What do contributed modules' and themes' version numbers mean?

As of 2006-11-11 and later

Now that the new system for releasing Drupal contributions has been installed, contributions have a more elaborate version string. The new strings indicate the version of Drupal core the contribution is compatible with, whether it is a stable or development release, and what specific "patch level" of the code it represents. These strings have the form:

CoreCompatibility-Major.PatchLevel[-Extra]

CoreCompatibility is required, and will be something like "4.7.x", or "5.x", to indicate what version of Drupal core this contribution is compatible with. Since the API for Drupal core does not change among stable releases, a module that is compatible with Drupal core 4.7.1 would also work with 4.7.3. This is why the version strings for contributions contain the character 'x' to show that they are compatible with any core release ("4.7.x") not just a specific version of core ("4.7.1").
Major is the major revision number, which indicates what set of functionality a given release has, if it is stable (bug-fixes only) or development (new features), and so on. The default branch for a given release of core (for example, the "DRUPAL-4-7" branch) will be major version 1. By convention, this major revision should always remain stable, and only security patches and bug fixes should be added to it. Optionally, project maintainers could create additional branches, which would have higher major versions (2, 3, etc.). These additional major revisions will be for whatever the maintainer of the project sees fit. It is up to the project maintainer to document on their project node and in their releases how they're using their own branches and what users of their modules should expect from any available major revision numbers. By convention, if the maintainer is adding new features to a module, they would use major revision 2 or higher.
PatchLevel is for a specific release of a given major revision. The first release would be patch level 0. As bugs are fixed, each new releases would have a higher patch level number. If the patch level is the letter "x", it indicates a development snapshot (see [-Extra] immediately below for more information).
[-Extra] is optional, and is for specifying things like "-dev", to indicate a development snapshot from the end of a CVS branch (as opposed to an official release from a CVS tag). These snapshots, by their nature, include changing code. It is therefore hard to know exactly what revisions of each file they contain, and this makes them more difficult to debug. Development snapshots also use "x" for the patch level to further indicate the variable nature of the code they contain.

Versions with extra tend to be less stable (development snapshots in particular are inherently unstable) so they should be avoided for production sites. Official releases uniquely identify an exact set of revisions of each file in a contribution. This identifier can be used in many places: the issue queue, the CVS repository, in forum posts, emails, and so on.

Some example version strings and what they mean should help clarify:

4.7.x-1.0 The initial (patch-level 0) stable release (major revision 1) of a module compatible with any version of Drupal core 4.7.*.
4.7.x-2.1 An updated (patch-level 1) new-feature release (major revision 2) of a module compatible with any version of Drupal core 4.7.*.
5.x-1.0-dev A nightly development snapshot ("-dev") of a stable release (major revision 1) of a module compatible with any version of Drupal core 5.*.

Contributed module versions prior to 2006-11-11

If you happen to have an older "release" of a contributed module, the version numbers are different. Prior to 2006-11-11, the version numbers for contributions where of the form "X.Y.0".

X.Y indicates the version of Drupal that a given module is compatible with. (A module with a version of 4.6 is compatible with Drupal core 4.6.1 and 4.6.2)
There was no patch level indicator for modules, so the version was always "X.Y.0". Modules were packaged automatically (readied for download in a tar.gz format) from the CVS repository whenever their maintainer updated them. The only way to know what specific code you had and if a newer "release" was available was to check the release date on the projects page to see if it had been updated.

Due to code changes in major Drupal core versions, modules are not expected to work with newer Drupal versions. If you wish to test, please do so on a test system. Otherwise, feel free to help the maintainer by submitting patches to update the module. If a maintainer is unavailable, you can apply to become the maintainer. (See the developers guide for more information).

Betas and release candidates

Before every official "x.0" stable release of a new major version of Drupal core, there are usually a handful of beta releases and release candidates that are made available. These releases are not yet stable enough for production use, but are essential milestones on the way towards the official release. They allow a much wider pool of users to test the latest code and provide feedback before the official stable release. These releases should only be downloaded and used by developers very familiar with Drupal or those wishing to help find bugs in the software.

Beta releases: These are the first to come out, and are therefore the least stable. During the period of beta releases, usability features are still considered, the translatable strings (help texts, words in the interface, etc) might be altered, and if absolutely necessary, the API or database schema could change (to fix a critical bug). Of course, other kinds of bug fixes are always applied.
Release candidates: Release candidates are usually only created once no more critical bugs have been reported in a given beta release. These are considered nearly stable code, something the Drupal development community is considering as a candidate to be released as the official .0 version. No more usability changes are made, and the translatable strings are usually unchanged at this point.

Some maintainers might choose to provide beta releases or release candidates of their contributed modules and themes (though this is not required). You should read the release notes carefully in these cases, since the details might vary across projects, though the basics explained here should hold (a "beta" is less stable than an "RC", etc).

Once a feature freeze is announced, no new features will be added to that version of Drupal. That version of Drupal's feature set is locked and any new features or change of behavior will need to go into the next release version.

What is "HEAD"?

In the forums you will see references to Drupal HEAD or just HEAD. You will also see references to Drupal CVS which is often the same thing. The name comes from the fact that Drupal uses the CVS version control system to track changes to the code, and in CVS, "HEAD" refers to the main development area (also known as "the trunk").

In Drupal core, HEAD is the name given to the version of Drupal core being worked on by developers right now. Of course, now that core is only using two digits for the version number (starting with the 5.0 release), there's no longer any ambiguity about what the next version of core will be called, so the use of "HEAD" to identify a release is no longer necessary. For example, now that the official 5.0 release of Drupal core is out, everyone knows that the next version of core under development will eventually become the 6.x release series, so the nightly snapshot releases are more properly called "6.x-dev", not "HEAD".

HEAD versions of Drupal core are not meant for use on production sites and should only be downloaded and used by developers who are very familiar with Drupal, or by testers who are helping to find bugs. HEAD is a moving target, and is prone to serious bugs and security holes.

When a contributed module or theme is tagged with HEAD, that means that it is the latest version on the main development branch. But "latest" can be any age -- perhaps over a year old! When a file was made for Drupal 4.3.x, it is HEAD of its own branch, but that does not mean you can run it with Drupal 4.7.x, or 5.5, or that it is necessarily compatible with any other module or core code that's tagged with HEAD.

In general, production sites should never use HEAD versions of any module or theme; they should always use official releases with real version numbers. Under the new release system, even the HEAD releases of contributed projects are required to include version information and to indicate which versions of Drupal core they are compatible with. A contribution without any official releases indicates that the contribution maintainer is not being very responsible, and you should use these contributions at your own risk.