Branches
The current development branch is always master. Stable branches, are named nm-<major>-<minor> (nma-<major>-<minor> for applet). Commonly only the last stable branch receives updates, but if necessary also older versions will receive important fixes. Fixes to stable branches must always be backported from the next-newer stable branch, via git cherry-pick -x.
Versioning for NetworkManager
Since 1.0, stable versions always have an even minor and an even micro number (eg, 1.0.6, 1.2.0, or 1.2.14). Development versions of master have an odd minor number (eg, 1.5.0, 1.11.2, 1.11.5), while development versions of stable branches have an odd micro version (1.0.1, 1.10.1, 1.10.5).
development release on master
You can do that anytime. On master, the version number are like 1.9.0-dev, 1.9.1-dev, 1.9.2-dev, ..., 1.11.0-dev, 1.11.1-dev, etc.
All you need to do, is bump nm_micro_version in configure.ac, and tag git tag -s 1.11.3-dev -m 'Tag 1.11.3 (development)' (example).
minor stable release on a stable branch
On the stable branch (after the major release is already out), the version numbers are always like 1.8.1-dev, 1.8.3-dev, 1.8.5-dev, ..., 1.10.1-dev, 1.10.3-dev, etc.
To do a minor stable release, first make sure that the NEWS file is up to date. Then, bump nm_micro_version in configure.ac to an even number, ensure that NM_VERSION_CUR_STABLE and NM_VERSION_NEXT_STABLE in shared/nm-version-macros.h.in match to the new minor release, and tag the release with git tag -s 1.10.4 -m 'Tag 1.10.4 (bad example). Immediately following the release commit, bump the version number again to an odd nm_micro_version in configure.ac, update NM_VERSION_NEXT_STABLE in shared/nm-version-macros.h.in, and tag git tag -s 1.10.5-dev -m 'Tag 1.10.5 (development) (bad example).
first release candidate of new major release
This can only follow a development release on master while there is no release-candidate in progress, hence the current version number on master is like 1.9.1-dev, 1.9.2-dev, ..., 1.11.1-dev, etc.
First make sure that NEWS file is up to date. Then bump nm_micro_version in configure.ac to 90 and tag as git tag -s 1.10-rc1 -m 'Tag 1.10-rc1' (example).
On master, you immediately bump nm_minor_version again to an odd number and reset nm_micro_version to 0. Also, bump NM_VERSION_CUR_STABLE and NM_VERSION_NEXT_STABLE in shared/nm-version-macros.h.in. Also, , and make sure that NM_VERSION_MIN_REQUIRED and NM_VERSION_MAX_ALLOWED in libnm-core/nm-version.h and libnm-util/nm-version.h are extended. Tag as git tag -s 1.11.0-dev -m 'Tag 1.11.0 (development)' (example).
Create a new stable branch on the first release candidate (git branch nm-1-10 1.10-rc1) which from now on diverges from master.
further release candidates for major release
You are on a stable branch, and the version number is like 1.10-rc1 (1.9.90), 1.10-rc2 (1.9.91), etc.
Just bump nm_micro_version in configure.ac by one (90, 91, 92, etc.) and tag as git tag -s 1.10-rc3 -m 'Tag 1.10-rc3' (example).
new major release
You are on a stable branch, and after a first release candidate, like 1.10-rc1 (1.9.90), 1.10-rc2 (1.9.91), etc.
Ensure that the NEWS file is up to date. Increment nm_minor_version to the next even number and reset nm_micro_version in configure.ac. Ensure that both NM_VERSION_CUR_STABLE and NM_VERSION_NEXT_STABLE in shared/nm-version-macros.h.in match the new release. Then tag git commit -s 1.10.0 -m 'Tag 1.10.0' (example).
Immediately afterwards on the stable branch (nm-1-10), bump nm_micro_version in configure.ac to 1. Also, bump the micro version of NM_VERSION_NEXT_STABLE in shared/nm-version-macros.h.in and tag as git commit -s 1.10.1-dev -m 'Tag 1.10.1 (development)' (example).
Now, merge the new release 1.10.0 back into master (example) with making sure that
the first-parent of new master's HEAD is 1.10.0. For example, by doing git checkout master && git reset --hard 1.10.0 && git merge origin/master. That point is, that git log --first-parent master follows 1.9.1-dev, 1.9.2-dev, ..., 1.10-rc1, 1.10.0, 1.11.2-dev, 1.11.3-dev, etc.
make sure that the new merge commit is identical to what you have already on origin/master, with the exception of keeping the NEWS file from 1.10.0, and bump nm_micro_version in configure.ac to the next number (git diff origin/master HEAD.
also, this merge marks a new development release on master. Hence tag it as git tag -s 1.11.1-dev -m 'Tag 1.11.1 (development)' or whatever your nm_micro_version is.
Versioning for applet and VPN plugins
The versioning for applet and VPN plugins follows the same scheme. In the following I talk about applet, but mean VPN plugins as well.
Note that the version number of NetworkManager, applet (and VPN plugins) does not need to be in sync and may diverge largely. In the past this was different, but that is no longer the case. There is one restriction though: the <major>.<minor> version of applet/plugins refers to the required libnm and server version. E.g. applet releases 1.8.0, 1.8.1-dev, 1.8.2, etc. all require a server and libnm version of 1.8.0 or newer.
So, unless master of the applet requires a newer libnm version, we only bump the micro version number. In the common cases, a release looks like
- ensure NEWS is up to date and you are ready for release.
bump the micro version to an even number in configure.ac (note that it must have been odd before). For applet, NMA_VERSION_CUR_STABLE and NMA_VERSION_NEXT_STABLE in src/libnma/nma-version.h.in must name the release you are about to do. Then tag with git tag -s 1.2.8 -m 'Tag 1.2.8' (example).
Immediately bump the micro version again to an odd number and tag git tag -s 1.2.9-dev -m 'Tag 1.2.9 (development)'. Again, for applet, you also need to bump NMA_VERSION_NEXT_STABLE in src/libnma/nma-version.h.in (example). Note that new micro versions of libnma may introduce new API. We have symbol versioning, right?
For stable branches like nm-1-2 or nma-1-2, micro releases work exactly the same as just explained on master.
In the very rare case when you need to bump the requirement to a new libnm version, you do instead:
Create a new stable branch from current master (git checkout -b nm-1-8 origin/master). Note that on applet, stable branches are called nma-<major>-<minor> instead). Then do a new release, exactly like in the steps above. You must first do a last micro release before incrementing the minor version on master. Note that the new stable branch now points to the release you just created (example).
Reset master to the new development snapshot with git checkout master && git reset 1.2.11-dev --hard.
Do a new release. Update the NEWS file, in configure.ac bump the minor version to 1.<micro>.0, where <micro> is an even number matching your required libnm API. For applet, make sure to bump NMA_VERSION_CUR_STABLE and NMA_VERSION_NEXT_STABLE to be identical to the new relase. Release and tag git tag -s 1.8.0 -m 'Tag 1.8.0'. In the same commit, adjust the required libnm version in configure.ac to require the correct libnm version. Note that if you want to use 1.8.0 API, you actually want libnm >= 1.7.*-dev, where you choose a 1.7.x development version that is recent enough to satisfy your requirement. Also, update the NM_VERSION_MIN_REQUIRED and NM_VERSION_MAX_ALLOWED` defines. Yes, this means, that your previous release 1.2.10 and your new 1.8.0 release are almost identical, except the version number, the NEWS file and the libnm requirement.
Let the commit be immediately followed by an odd development version again: git tag -l 1.8.1-dev -m 'Tag 1.8.1-dev (development)'. Make sure to bump NMA_VERSION_NEXT_STABLE again.
... hack on the next micro release on master (1.8.2).
library version
For libnm.so, libnm-util.so, and libnm-glib we use symbol versioning. We hence do not change -version-info, because it could not model the fact that a minor stable release might contains new backported ABI (link).
Checklist for releases of NetworkManager
make sure that make distcheck passes (this should be covered by various CI tests already)
- take special care of Big Endian architectures and 32 bit vs. 64 bit.
Ensure that any new API has Since: tags added in the code documentation, and has an appropriate NM_AVAILABLE_IN_* annotation in the header file.
You can diff libnm-util.ver, libnm-glib.ver, and libnm.ver against the previous release to see all newly-added API.
In the .ver files, all new API should be in a new section for this release, not added to an existing section.
- Ensure documentation is correct
- fix any trivial warnings (argument name mismatches, undocumented functions, etc)
- Fix any obvious errors in GObject Introspection data:
inspect g-ir-scanner output for trivial errors and fix them
- Ensure that NEWS is updated for each component based on the git changelog, for notable or large changes. Trivial stuff like very small bug fixes don't really need to be mentioned.
Look at the versioning howto above how to handle bumping the version number.
create the tarball via ./contrib/fedora/rpm/build_clean.sh --srpm
make sure, that the created tarball is exactly done in a git-checkout of the tagged release. In other words, make sure that NM_GIT_SHA records the correct commit id.
scp ./NetworkManager-*.tar.xz "$user@master.gnome.org:" and run ftpadmin install on master.gnome.org (See gnome releasing).
Ensure the new tarballs show up at https://download.gnome.org/sources/ (happens after a short delay)
- Add the new release version to the appropriate gnome.org bugzilla components; we only need to do this for actual stable releases like 0.9.6, don't bother with micro releases like 0.9.6.2
Mail release announcements to networkmanager-list@gnome.org and any other appropriate lists
Checklist for releases of nm-applet or VPN plugins
Note that releases of NetworkManager, applet, and VPN plugins are no longer done in sync. Each component can be released independently anytime. This also means, that the version numbers diverge. Note that the version major.minor number of applet and VPN plugins tells the required NetworkManager API. That is, nm-applet 1.8.x requires at least NetworkManager API 1.8.0 or newer.
Make sure 'git pull; make clean; make; make distcheck' passes
- take special care of Big Endian architectures and 32 bit vs. 64 bit.
(for applet) Ensure that any new API has Since: tags added in the code documentation, and (for 0.9.10 and later) has an appropriate NMA_AVAILABLE_IN_* annotation in the header file for libnma.
You can diff libnma.ver, and libnm-gtk.ver against the previous release to see all newly-added API.
In the .ver files, all new API should be in a new section for this release, not added to an existing section.
- Ensure documentation is updated by doing the following:
cd docs
make clean
make
- fix any trivial warnings (argument name mismatches, undocumented functions, etc)
- for applet, fix any obvious errors in GObject Introspection data
inspect g-ir-scanner output for trivial errors and fix them
- Ensure that the library sonames are bumped appropriately if API was added or changed
Follow the libtool version info rules
- Triple-check the old soname and the new soname and make sure the changes are sane (libtool versioning is confusing!)
- Ensure that NEWS is updated for each component based on the git changelog, for notable or large changes. Trivial stuff like very small bug fixes don't really need to be mentioned.
Look at the versioning howto above how to handle bumping the version number.
make the release with git clean -fdx && ./autogen.sh && make distcheck. Ensure that your head is on the right release commit, so that NM_GIT_SHA is recorded correctly.
scp ./*-*.tar.xz "$user@master.gnome.org:" and run ftpadmin install on master.gnome.org (See gnome releasing).
Ensure the new tarballs show up at https://download.gnome.org/sources/ (happens after a short delay)
Mail release announcements to networkmanager-list@gnome.org and any other appropriate lists