WeeChat specifications

Practical semantic versioning


WeeChat uses two number for versions (X.Y) and sometimes three in case of severe bugs or security issues fixed in versions already released (X.Y.Z). The numbers X and Y have same meaning, they are incremented in the same way.


Purpose of this specification is to adopt a “practical” Semantic Versioning.
As major breaking changes are introduced in version initially numbered 3.9, the goal is to bump to 4.0.0.
All subsequent releases will follow this “practical” semantic versioning.

Out of scope

The versions already released or fix releases based on versions already released are not concerned by these changes.


Version number

The version number is now always on three digits X.Y.Z, where:

The version follows the Semantic Versioning specification with some changes to be less strict, that’s why it’s called “practical” semantic versioning.

For example breaking changes in C API functions that are not widely used don’t bump the major version number.

Display of version

The version displayed by weechat -v is now always on three digits:

$ weechat -v

Same for the output of command /v in WeeChat:

WeeChat 4.0.0 [compiled on Mar 11 2023 10:58:35]

Rules for version number

Rules to increment the version number:

As WeeChat is constantly changing, new releases increment at least minor and sometimes major version number.
The patch version is only made on maintenance branches (e.g. for releases done in past, not the future version).

Minor bugs found are not back-ported to old branches and are fixed only in the next release (new major and/or minor version).

Major version number

These changes result in a bump of major version number:

Examples of changes that should have bumped major version number if semantic versioning was used:

Minor version number

These changes result in a bump of minor version number:

Because of internal version numbering limitations, the max value for this minor version number is 255.
In practice, as there are a lot of improvements in each WeeChat release, this number should rarely exceed 10 or 15.

Patch version number

The patch version number is incremented only for severe bugs or security issues that are discovered on a version already released.

Because of internal version numbering limitations, the max value for this patch version number is 255.
As most bugs are fixed in the next release, such versions are rare, and the patch version number should rarely exceed 1 or 2.

Release process

After a release where major and/or minor have been bumped, the next version by default has minor number bumped.

For example after release of 4.0.0, the development version becomes 4.1.0-dev.

In case major breaking changes are introduced, the development version is immediately bumped to 5.0.0-dev.

In case a severe bug or a security issue must be fixed in 4.0.0, a new branch is created from v4.0.0 tag, and the version is set to 4.0.1-dev.
The version on master branch remains 4.1.0-dev or 5.0.0-dev.

Simulation of semantic versioning on old releases

If semantic version was used, versions would have been:

Version released Would have been… Major bumped because of…
1.0 1.0.0  
1.0.1 1.0.1  
1.1 2.0.0 New trigger regex format
1.1.1 2.0.1  
1.2 2.1.0  
1.3 2.2.0  
1.4 2.3.0  
1.5 3.0.0 New pointer in callbacks
1.6 3.1.0  
1.7 3.2.0  
1.7.1 3.2.1  
1.8 3.3.0  
1.9 3.4.0  
1.9.1 3.4.1  
2.0 3.5.0  
2.0.1 3.5.1  
2.1 3.6.0  
2.2 3.7.0  
2.3 3.8.0  
2.4 3.9.0  
2.5 4.0.0 Aspell renamed to Spell
2.6 4.1.0  
2.7 4.2.0  
2.7.1 4.2.1  
2.8 4.3.0  
2.9 5.0.0 Bars bg color (function bar_new), modifier weechat_print
3.0 5.1.0  
3.0.1 5.1.1  
3.1 5.2.0  
3.2 6.0.0 XDG directories
3.2.1 6.0.1  
3.3 6.1.0  
3.4 7.0.0 Function hdata_search
3.4.1 7.0.1  
3.5 7.1.0  
3.6 7.2.0  
3.7 7.3.0  
3.7.1 7.3.1  
3.8 8.0.0 String / UTF-8 functions
3.9 9.0.0 Autotools removed, case sensitive identifiers, new keys

Breaking changes

To prevent incrementing major version too often, the major breaking changes will be grouped together.

For example when the major version is bumped, some deprecated functions can be removed (especially those marked as deprecated a long time ago).


The changes must be implemented in this order:

  1. Rename version 3.9 to 4.0.0.
  2. Add note about semantic versioning in Contributing.adoc.