Page MenuHomeFreeBSD
Differential D47496

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

Authored by freebsd_ny-central.org on Nov 9 2024, 11:12 AM.
Tags
None
Referenced Files
Unknown Object (File)
Fri, Jul 24, 11:15 PM
Unknown Object (File)
Fri, Jul 24, 10:29 PM
Unknown Object (File)
Wed, Jul 22, 9:07 PM
Unknown Object (File)
Tue, Jul 21, 10:29 AM
Unknown Object (File)
Tue, Jul 21, 4:54 AM
Unknown Object (File)
Mon, Jul 20, 5:45 PM
Unknown Object (File)
Sat, Jul 18, 6:26 PM
Unknown Object (File)
Sat, Jul 18, 7:48 AM
View All Files
Subscribers
None

Details

Reviewers
jrm
emaste
wosch
ziaee
Group Reviewers
docs
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

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
No Lint Coverage
Unit
No Test Coverage
Build Status
Buildable 60481
Build 57365: arc lint + arc unit

Event Timeline

freebsd_ny-central.org requested review of this revision.Nov 9 2024, 11:12 AM
freebsd_ny-central.org created this revision.
freebsd_ny-central.org added a reviewer: docs.Nov 9 2024, 11:13 AM
Harbormaster completed remote builds in B60458: Diff 146198.Nov 9 2024, 11:13 AM
freebsd_ny-central.org added a reviewer: wosch.Nov 9 2024, 11:13 AM
ziaee accepted this revision.Nov 9 2024, 3:28 PM
This revision is now accepted and ready to land.Nov 9 2024, 3:28 PM
jrm accepted this revision.Nov 9 2024, 4:09 PM

Looks good to me. Thank you.

jrm added a comment.Nov 9 2024, 7:06 PM

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 added inline comments.Nov 9 2024, 7:50 PM
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 updated this revision to Diff 146213.EditedNov 9 2024, 8:24 PM
  • 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
This revision now requires review to proceed.Nov 9 2024, 8:24 PM
Harbormaster completed remote builds in B60464: Diff 146213.Nov 9 2024, 8:24 PM
freebsd_ny-central.org marked 3 inline comments as done.Nov 9 2024, 8:25 PM
freebsd_ny-central.org updated this revision to Diff 146214.Nov 9 2024, 8:27 PM
  • Fixed a typo I introduced.
Harbormaster completed remote builds in B60465: Diff 146214.Nov 9 2024, 8:27 PM
freebsd_ny-central.org updated this revision to Diff 146234.EditedNov 10 2024, 11:49 AM

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

Harbormaster completed remote builds in B60479: Diff 146234.Nov 10 2024, 11:49 AM
freebsd_ny-central.org updated this revision to Diff 146236.Nov 10 2024, 12:24 PM

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
Harbormaster completed remote builds in B60480: Diff 146236.Nov 10 2024, 12:24 PM
freebsd_ny-central.org updated this revision to Diff 146237.Nov 10 2024, 12:30 PM
  • Fixing a typo I introduced.
Harbormaster completed remote builds in B60481: Diff 146237.Nov 10 2024, 12:30 PM
ziaee mentioned this in D57937: committers-guide: Use macros for branch examples.Jun 29 2026, 4:30 AM
ziaee added a comment.Jun 29 2026, 4:38 AM

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 accepted this revision.Jun 30 2026, 8:29 AM
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.

This revision is now accepted and ready to land.Jun 30 2026, 8:29 AM
ziaee added a comment.Sun, Jul 12, 9:16 AM

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

Revision Contents
Changeset List

PathSize
documentation/
content/
en/
articles/
committers-guide/
74 lines

Diff 146237

View Options

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

Loading...