Choosing a version number #

This page is for designers about to release. A version number is a promise to your users about what changed. Choose it with care: once a tag is pushed, the number is used up forever.

The procedure #

1. Look at what is published, not at your memory or your working copy (Checking what is already published):

   git fetch --tags
   git tag -l 'v*' --sort=version:refname | tail -5
   gh release list --limit 10

2. Take the highest published number from both lists. A tag can exist without a release, and a release can exist for a tag your clone has not fetched.

3. Raise the last position by one: 1.0.23 becomes 1.0.24; 0.1.9 becomes 0.1.10 (After .9 comes .10).

4. Move a higher position only on purpose, when the release means something different:

   Move	When	Example
   The last position	Fixes, improvements, new templates, anything that keeps working for existing users	1.0.23 to 1.0.24
   A middle position	A deliberate step, for example a new minimum Exponential or PHP version, or a changed API for template authors	1.4.x to 1.5.0
   The first position	A redesign or a break that needs users to act	1.x to 2.0.0

5. Write the number into every version field (Keeping every version field in sync).

What the published themes do #

Read gh release list for a real pattern: sevenx_themes_simple counts 1.0.20, 1.0.21 ... 1.0.24; sevenx_themes_media reached 1.5.70; cjw_themes_jumper counts 0.1.2 to 0.1.6. In each, only the last position moves from one release to the next.

Things to avoid #

• Reusing a number, even one whose release was deleted: Packagist and users may already have it.
• Skipping numbers to "look bigger".
• Letting a release script pick "the newest tag" by plain name sorting (Sorting tags correctly).

Related pages #

• Bumping the version before the tag
• Breaking changes and the next major version
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.