[articles][committers-guide]: streamlining stable/N and releng/N.n syntax

[freebsd_ny-central.org]

Summary

As outlined in https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=279503 there are
various ways we are listing stable/N and releng/N.n - sometimes with numbers,
sometimes not.

I'm suggesting to migrate everything into one common format. What I have not
resolved yet (and would appreciate feedback on): there are still numerous
examples with i.e. stable/13 (I updated from stable/12). It would make sense to
simply change them all into a stable/N and releng/N.n format.

Ed made the point that he received issue reports for people misunderstanding the
placeholder syntax, so maybe it makes sense to leave a handful of examples with
numbers?

PR: 279503

[jrm]

Looks good to me. Thank you.

[jrm]

This seems to do well to address @emaste's concern (in bug 279503) about generic names by including concrete examples such as

(where N is the major release number, i.e. up to 14 as of 2024)

Let's give it a few days to see if anyone else has comments. If not, I'll commit.

[emaste]

documentation/content/en/articles/committers-guide/_index.adoc

463–464

897–899

These form part of the same example, so it doesn't make sense to have ...stable-14 in the first line and stable/13 in the second.

943–945

We should definitely be consistent, but I'm not sure if N.n or X.Y is the preferable form.

[freebsd_ny-central.org]

• version numbers and 1st person statements fixed
• switched to X.Y because it's used in other places of the docs
• replaced the first person "I" statements except for the Q&A

[freebsd_ny-central.org]

• Fixed a typo I introduced.

[freebsd_ny-central.org]

Additional improvements after receiving feedback on FreeBSD Forums

• replaced abbreviations
• fixed a typo/number with its variable representation
• simplified listing of branch names

Reviewed by: Erichans

[freebsd_ny-central.org]

Replacing version numbers with variables (where possible), fixing vars.

• replacing 14 with betarel-current-major
• replacing 14.2 with betarel-current
• fixing dev-src-all et al mailing list variables

[freebsd_ny-central.org]

• Fixing a typo I introduced.

[ziaee]

This never got committed, but eventually I was frustrated with reviewing PRs to bump release names and branches and spent the last few releases building out macros to do this. I have a draft here: https://reviews.freebsd.org/D57937, and you can see it in practice on the bsdinstall or jails chapters of the handbook. The macros are in doc/shared/releases.adoc and look like this:

// Current latest production RELEASE.
:rel-latest-major: 15
:rel-latest: {rel-latest-major}.1
:rel-latest-next: {rel-latest-major}.2
:rel-latest-previous: {rel-latest-major}.0

// Current latest legacy RELEASE.
:rel-legacy-major: 14
:rel-legacy: {rel-legacy-major}.4
:rel-legacy-next: {rel-legacy-major}.5
:rel-legacy-previous: {rel-legacy-major}.3

[wosch]

In D47496#1328183, @ziaee wrote:

This never got committed, but eventually I was frustrated with reviewing PRs to bump release names and branches and spent the last few releases building out macros to do this.

I like the idea of using a macro instead of hard coded values.

[ziaee]

I committed my diff switching branch names to macros. However there are other improvements in this patch that could be rebased.