Skip to content

releases.adoc: Fix rel-legacy-next macro#662

Open
BigSneakyDuck wants to merge 1 commit intofreebsd:mainfrom
BigSneakyDuck:patch-8
Open

releases.adoc: Fix rel-legacy-next macro#662
BigSneakyDuck wants to merge 1 commit intofreebsd:mainfrom
BigSneakyDuck:patch-8

Conversation

@BigSneakyDuck
Copy link
Copy Markdown
Contributor

An instance of rel-legacy-previous was clearly intended as rel-legacy-next.

Stumbled upon this because I have been working on some documentation that would benefit from having an exemplar version number and didn't want to introduce it in a way that would need bumping. So I was about to propose something almost identical to these macros, then was pleasantly surprised to discover I'd been beaten to it!

An instance of rel-legacy-previous was clearly intended as rel-legacy-next.

Signed-off-by: [email protected]
@BigSneakyDuck
Copy link
Copy Markdown
Contributor Author

BigSneakyDuck commented Apr 27, 2026

A few observations for @concussious that may or may not be useful, sorry: in my now abandoned proposal that was essentially a duplicate of this one, I wasn't going to call the older major version number "legacy" because the word "legacy" has a particular meaning for FreeBSD: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=273017#c20

Generally speaking, as soon as X.(Y+1) is released X.Y is "legacy", and once (X+1).1 is released X.* is "legacy", but re@ may diverge from this on occasion (i.e. that's not part of the definition, just what I expect will usually be the case).

Hence 14.4 is listed as "production" not "legacy" at https://www.freebsd.org/releases/ until 15.1 is released, which makes the comments // Current latest production RELEASE and // Current latest legacy RELEASE slightly misleading during these changeover periods. Assuming the (X+1).1 rule is applied, the 6 months between (X+1).0 and (X+1).1 means two major versions will both be "production" for 25% of the 2-year cycle, so this state of affairs is not especially unusual. (Another wrinkle is that at any moment in time where it is defined, :rel-latest-previous: will always be "legacy" of course!)

Once 13 reaches EOL, there will only be two major versions supported simultaneously going forward, according to https://lists.freebsd.org/archives/freebsd-announce/2024-July/000143.html

As a result my proposed names for the two were going to be :lo-major-release: and :hi-major-release: to get around the "legacy"/"production" complication, though those were just tentative suggestions. I thought I'd mention this now in case it's useful food for thought before putting these macros into widespread use.

Obviously :rel-legacy-next: and rel-latest-previous won't always be defined. But the current schedule does guarantee :rel-latest-major: will have had at least the .0 release and not .4 or higher, while :rel-legacy-major: will have had at least the .3 release but not more than .6. That might be useful to remember for writing some documentation examples where all that matters is the numbers look plausible and not totally outdated, so could use fixed minor versions rather than having to worry about whether :rel-legacy-next: and rel-latest-previous actually exist.

Some final minor suggestions: perhaps some of the instances of current in the comments could be changed to a synonym ("at present"?) to avoid confusion with CURRENT. And while I know the file is titled "releases", some places in the documentation talk about CURRENT so perhaps a macro to say that's 16 or 16.0 (:rel-next-major:?) would be useful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant