svn primer translation to git

[Kristof Provost]

On 25 Jun 2020, at 8:24, Emanuel Haupt wrote:
> Ed Maste <emaste at freebsd.org> wrote:
>> We currently have a FreeBSD Subversion primer in the committer's
>> guide:
>> https://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/subversion-primer.html
>>
>> I've started a translation of this into a Git primer, at:
>> https://hackmd.io/ML5TSl8mQ5-27B5eqDf7YA?view
>>
>> I'm particularly interested in feedback on how much git background /
>> theory of operation we want to include here (vs referring to external
>> documentation).
>
> Thank you for writing the document.
>
> Maybe we could address the convention [1] that with git commit 
> messages
> usually begin with a subject, followed by a blank line and then the
> commit body.
>
> This schema produces beautiful commit logs on web-based DevOps 
> lifecycle
> tools such as github, gitlab, gitea.
>
That’s a good point.

Most of our commit messages already follow this form, so it shouldn’t 
be a painful adjustment.

I’ve had a look at the last few commits, and only the MFCs stand out 
as needing a little attention in that area.
To grab a random example:

	  MFC r362183

	  netmap: vtnet: fix races in vtnet_netmap_reg()

	  The nm_register callback needs to call nm_set_native_flags()
	  or nm_clear_native_flags() once the device has been stopped.
	  However, in the current implementation this is not true,
	  as the device is stopped by vtnet_init_locked(). This causes
	  race conditions where the driver crashes as soon as it
	  dequeues netmap buffers assuming they are mbufs (or the other
	  way around).
	  To fix the issue, we extend vtnet_init_locked() with a second
	  argument that, if not zero, will set/clear the netmap flags.
	  This results in a huge simplification of the nm_register
	  callback itself.
	  Also, use netmap_reset() to check if a ring is going to be
	  re-initialized in netmap mode.

The original commit already followed the ‘headline summary, expanded 
body’ rule. This MFC would also work (often there’s no blank line 
between the ‘MFC’ and the next line), but I do wonder if `MFC 
r362183: netmap: vtnet: fix races in vtnet_netmap_reg()` wouldn’t be 
better.

It’s a minor point, but we may as well document a choice now. I have 
my preferences, but most of all I’d prefer uniformity.

Best regards,
Kristof