Re: [RFC] Introduce semantic versioning 2.0.0 to FreeBSD releases

On Wed, 25 Feb 2026 14:27:14 +0800
Philip Paeps <[email protected]> wrote:

> On 2026-02-25 14:17:28 (+0800), Minsoo Choo wrote:
> > Currently FreeBSD uses a variant of semantic versioning for releases 
> > (e.g. 15.0-RELEASE-p1) where backward compatibility can be broken 
> > (e.g. deprecation of a utility)in a new major version, new features 
> > are added in minor versions, and security fixes are introduced in a 
> > new patch version.
> >
> > FreeBSD's git repository reserves semantic versioning style patch 
> > version (aka third version) in git tags but it has been unused for a 
> > long time (e.g. 15.0.0-p1). This results in having two patch version 
> > placeholders where one is unused and might​​ cause confusions for 
> > some newcomers. The last git tag that contains patch version in 
> > semantic versioning format is 5.2.1. After that, tags for both patch 
> > version placeholders are missing until 13.4.0-p2 and 14.1.0-p6 (re@, 
> > why are we missing these tags? Can we recover them?), and we cannot 
> > track what happened in the past.
> 
> We only started adding the -pX tags in Git after 13.4-RELEASE-p2.  I 
> never went back in time to create the tags before that.  It wouldn't be 
> too difficult to do -- merely tedious.
> 
> See also: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=279416
> 
> Note that 13.4.1 would be "13.4.1-RELEASE".  We have not done a release 
> like that for a very long time.
> 
> The -pX refer to patches released by the security team.  These are not 
> releases.  The last time we had to re-do a release was (apparently) 
> 5.2.1-RELEASE.  I thought there was a more recent one but my memory is 
> fuzzy.

As seen in bsd-family-tree, 5.2.1 is the last release that has "2 dots"
versioning.

  https://github.com/freebsd/freebsd-src/blob/main/share/misc/bsd-family-tree


> > Thus, I propose using semantic versioning 2.0.0 [1] starting from 
> > FreeBSD 16. Major and minor versions will have the same roles as 
> > before. For patch versions, I propose including bug fixes as well as 
> > security patches. For bugs, I mean existing things that do not produce 
> > expected behaviour that has "Fixes: " metadata in git commit message.
> >
> > Many teams need to be involved in discussions and decisions for this 
> > change. For now, I can name re@, clusteradm@, secteam@, and probably 
> > core@. Once we reach community consensus, I will bring this topic to 
> > those teams.
> >
> > [1] https://semver.org
> 
> I have no objection as long as we commit to one system and stick to it. 
> :)
> 
> I suspect we can't start doing this until freebsd-update is dead and 
> burried.
> 
> Philip

IMHO, "2 dots versioning" should only be used when planned patch release
turns out to have unavoidable backward incompatibilities that at least
some ports are forced to take care of.

Usually, AFAIK, *-p* patch releases does NOT bump __FreeBSD_version in
sys/sys/param.h, which is incremented when notable new features are
added or backward incompatibilities are unavoidably introduced, to
notify ports (and incremental builds of base) something need to take
care of happened. This is the source of OSVERSION on ports framework.

Note that this bump not always mean everything are affected,
at least in additions of features. In this specific type of
bumps, anything want new features are needed to be updated,
but not for others. This is because why I think forcible rebuilds
of "everything in the builder repo" on poudriere is overkill.

Regards.

-- 
Tomoaki AOKI    <[email protected]>