handbook/cutting_edge: document the n-number

[imp]

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

[debdrup]

Seems like an excellent idea.

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

[markj]

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_gundo.com]

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]

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

601

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

[debdrup]

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

[imp]

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.

[imp]

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

[imp]

be less terse

[erj]

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.

[pauamma_gundo.com]

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

622

[imp]

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.

[imp]

pau's an -> a typo

[ceri]

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/

[imp]

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]

address ceri's n-number comment

[imp]

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]

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

[imp]

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

[ceri]