Developing a major version update

You must update to a major version when changes you’re making in a potential new version can’t guarantee backward compatibility for the module’s users. For example, you’ll make this change if you change your module’s public API such that it breaks client code using previous versions of the module.

Note: Each release type – major, minor, patch, or pre-release – has a different meaning for a module’s users. Those users rely on these differences to understand the level of risk a release represents to their own code. In other words, when preparing a release, be sure that its version number accurately reflects the nature of the changes since the preceding release. For more on version numbers, see Module version numbering.

See also

Considerations for a major version update

You should only update to a new major version when it’s absolutely necessary. A major version update represents significant churn for both you and your module’s users. When you’re considering a major version update, think about the following:

Branching for a major release

The most straightforward approach to handling source when preparing to develop a new major version is to branch the repository at the latest version of the previous major version.

For example, in a command prompt you might change to your module’s root directory, then create a new v2 branch there.

$ cd mymodule
$ git checkout -b v2
Switched to a new branch "v2"

Diagram illustrating a repository branched from master to v2

Once you have the source branched, you’ll need to make the following changes to the source for your new version:

For publishing steps, see Publishing a module.