Page MenuHomeFreeBSD

handbook/cutting_edge: document the n-number
ClosedPublic

Authored by imp on Jun 29 2021, 3:12 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sat, Jan 7, 8:55 AM
Unknown Object (File)
Fri, Jan 6, 4:23 AM
Unknown Object (File)
Dec 2 2022, 9:33 AM

Details

Summary

Document how to convert a git hash into a 'n' number. I've been asked
this a few times and it would be good to have an easy, linkable answer.
It seems to fit best here.

Sponsored by: Netflix

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

imp requested review of this revision.Jun 29 2021, 3:12 PM
imp created this revision.
debdrup added a subscriber: debdrup.

Seems like an excellent idea.

I assume it passes a local test in your browser of choice.

This revision is now accepted and ready to land.Jun 29 2021, 3:32 PM

Thank you!

documentation/content/en/books/handbook/cutting-edge/_index.adoc
601

The first part of this sentence isn't right, but I'm not sure what it should be.

618

Capitalization of "git" is inconsistent.

632

I'd phrase the first part a bit differently, like "However, when bug fixes are committed, this number makes it easy to quickly determine whether the fix is present in the currently running system." or something like that.

Might be worth mentioning that security and errata notices use this number for older branches.

pauamma added inline comments.
documentation/content/en/books/handbook/cutting-edge/_index.adoc
601

Guessing "on" is a typo for "one", but that would still feel stilted to me. Perhaps "No matter what OS version is running"?

erj added inline comments.
documentation/content/en/books/handbook/cutting-edge/_index.adoc
601

"Regardless of which OS version one is running, ..." ?

I clearly shouldn't review things when I'm tired. Sorry. :(

This revision now requires review to proceed.Jun 29 2021, 4:02 PM
documentation/content/en/books/handbook/cutting-edge/_index.adoc
601

how about the less awkward:

FreeBSD provides version information compiled into the kernel.
man:uname[1] retrieves this information, for example:
618

thanks. I have an eye for it, but not a good one.
The rule, for others, is that we use "Git" to refer to the whole Git system and only use "git" when it's in commands.

632

Sure. I reworked it.

Update based on feedback in review
typos fixed
awkward sentences reworked
Expanded a bit on when/how to use n-numbers

This revision is now accepted and ready to land.Jun 29 2021, 4:07 PM
This revision now requires review to proceed.Jun 29 2021, 4:12 PM
imp marked 5 inline comments as done.Jun 29 2021, 4:14 PM
documentation/content/en/books/handbook/cutting-edge/_index.adoc
618

Ok, that is useful information.

622–623

Is this explained somewhere else? I'm not sure this is the section people would look at to find an explanation of this phenomenon.

documentation/content/en/books/handbook/cutting-edge/_index.adoc
622
documentation/content/en/books/handbook/cutting-edge/_index.adoc
622–623

I can't find it with a quick grep (which means -dirty isn't documented elsewhere).
There's like a section on uname that I'm not immediately finding, though, and would be open to putting a full explanation there and having a pointer from here.

ceri added inline comments.
documentation/content/en/books/handbook/cutting-edge/_index.adoc
600

Add something under here to introduce why we care. Perhaps:

"When tracking down bugs it is important to know which versions of the source code have been used to create the system exhibiting an issue."

605

uname -a

625

'n-number' or 'N-number' ? Can we be consistent?

637

s/the/an/

documentation/content/en/books/handbook/cutting-edge/_index.adoc
622–623

"likely a section" is what I meant.
And I'm open to doing that fuller explanation now or in the future.

imp marked an inline comment as done.

address ceri's n-number comment

imp marked 6 inline comments as done.Jun 29 2021, 4:40 PM
imp added inline comments.
documentation/content/en/books/handbook/cutting-edge/_index.adoc
600

Good suggestion.

625

good catch. n-number is what I think I'll use unless the word needs to be capitalized in context.

637

I think this is OBE, but if not, please resubmit.

imp marked 2 inline comments as done.

The rest of Ceri's suggestions... I'd overlooked them and thought
there was only one...

ah, from the email the the->an suggestion was clear and a good idea.

This revision is now accepted and ready to land.Jun 29 2021, 6:19 PM
This revision was automatically updated to reflect the committed changes.