Explain briefly how to write a good commit message

[iglpdc]

Currently, we don't explain much on how to write a commit message: what the contents should be, how long it should be, or what's the point of it. I think that, without going into much details, a good explanatory sentence in the part of the lesson where the first commit is created would be nice.

An entry for "commit message" could be also added to the lesson glossary in reference.md.

See also the discussion in #70.

[wking]

On Sun, Mar 15, 2015 at 06:19:13AM -0700, Ivan Gonzalez wrote:

I think that, without going into much details, a good explanatory
sentence in the part of the lesson where the first commit is created
would be nice.

Either from this sentence or from the glossary entry, I think we
should link to Tim Pope's note 1, since that's the best balance of
clear, concise guidelines and the reasoning behind them that I've
found.

The main goal of a commit message is motivating the change, and I
really like Justin Hileman's “How to Git pretty” 2 for its emphasis
on creating clear, understandable history. No amount of commit
message composition will make it easy to understand a huge commit
making multiple orthogonal changes ;). Rewriting history may be too
big a step for novices struggling with creating history at all, but I
don't think it's so big a step that we can't link to that talk from
somewhere later in the lesson.

[gvwilson]

We could ask Pope and Hileman if we could incorporate their text into our lesson (with attribution).

[wking]

On Sun, Mar 15, 2015 at 09:31:06AM -0700, Greg Wilson wrote:

We could ask Pope and Hileman if we could incorporate their text
into our lesson (with attribution).

I don't think we actually want more than a sentence explaining that
you should compose your commit message with an eye towards a concise,
unique summary, followed by a body with motivation and implementation
details. All of the long-line stuff, imperative phrasing, etc., is
nice, but in my opinion not important enough for space in the lesson
itself. I'd rather have the single sentence with a link then embed
Pope's example and surrounding text.

We probably can't embed Hileman's stuff, since it's a slide show. I
don't think we want to embed it either, since again, I don't think the
novice lesson gets folks to the point where I'd want to talk about
rewriting history. At least, I'd want them to have some quality time
with the novice material to let the concepts gel before getting into
rewriting.

[gvwilson]

I think 500-800 words would be a good fit for `discussion.md`.

[daisieh]

I'm not sure that I agree that we need to spend time explaining best practices for commit messages. Really, if we're starting people with collaborating with themselves for their own future edification, all we need to teach is "write something that will make sense to future you" and then they should be able to figure it out from there.

[wking]

On Sun, Mar 15, 2015 at 03:26:18PM -0700, Daisie Huang wrote:

I'm not sure that I agree that we need to spend time explaining best
practices for commit messages.

I think the only proposed change to the taught lessons here is a
single sentence suggesting folks think about a clear, concise summary
and optional follow-up motivation/implementation details. We should
probably just submit that in its own PR. Does anyone want to work
that up? I'll handle it if nobody else wants to.

After the taught sentence (about which I think everyone agrees),
there's disagreement on where to store additional follow-up
information. My preference is to link-out to external sites.
@gvwilson wants to inline the external docs in discussion.md, and
@iglpdc suggests a glossary entry. I think we can continue to hash
that out here while the taught sentence lands through a different PR.

… and then they should be able to figure it out from there.

Just because they could figure it out on their own doesn't mean we
can't help them along by pointing interested parties at good
references. It's harder to sort the wheat from the chaff when you're
new to a topic.

[gvwilson]

I would really like to have a short example in our notes - it'll take 2-3 minutes of class time, and would add a lot of value.

[wking]

On Mon, Mar 16, 2015 at 11:37:28AM -0700, Greg Wilson wrote:

I would really like to have a short example in our notes - it'll
take 2-3 minutes of class time, and would add a lot of value.

I think the current preference for the one-line commit messages is
because we're trying to stay on the command line and out of the
possibly-unfamiliar editor. Folks likely just learned about the
command line (maybe a few hours before this lesson), and may have
never seen their local text editor either. Sometimes it's too awkward
to avoid using the editor (e.g. I don't think we want to use >>
redirects to add content to mars.txt ;), but ‘git commit -m '…'’ works
well enough that I'm not sure it's worth dragging complete novices
into an editor to walk them through composing a good commit message.

I think spending a few minutes live-coding a good commit message and
pointing out its features does make sense if the students are more
comfortable in their own editors, but I'm fine leaving that up to
instructor initiative. A link to Tim Pope's post should give them
sufficient background on the technical considerations, so I'd rather
not rehash that locally. I'd be fine with a bit of additional patter
explaining the intended audience (reviewers and future devs, which may
include your future self) and the intended message (a summary of the
change, motivational details, possibly notes on tricky implementation
issues, notes on alternative implementations and why they were
rejected, …). Maybe a callout box? Or a long-form discussion entry
(see swcarpentry/DEPRECATED-lesson-template#199).

In any case, if we go with a longer-form discussion, I think we want
to make it something that an instructor has to opt into, and not
something that's part of the default lesson flow. Personally, I'd
rather move the longer discussion into an intermediate Git lesson,
since it's a lot easier to motivate these messages if the students
have already internalized the general flow and you're really focused
on tuning the feature branch, code review, and project maintenance
workflows.

[daisieh]

I definitely agree that this is something very useful for the intermediate Git lesson.

[iglpdc]

On Mon, Mar 16, 2015 at 1:23 PM, W. Trevor King notifications@github.com
wrote:

We should
probably just submit that in its own PR. Does anyone want to work
that up? I'll handle it if nobody else wants to.

After the taught sentence (about which I think everyone agrees),
there's disagreement on where to store additional follow-up
information. My preference is to link-out to external sites.
@gvwilson wants to inline the external docs in discussion.md, and
@iglpdc suggests a glossary entry. I think we can continue to hash
that out here while the taught sentence lands through a different PR.

I totally agree. I think that we could do two PRs, one for with a
sentence in the main lesson, and another one with a longer discussion, be a
glossary entry, a link to external stuff to whatever.

@wking, do you mind if I send out an email to discuss to see if a new
instructor wants to take care of the short sentence one? I think it's easy
enough, given that you posted here most of the relevant links, and could be
a good first PR for someone. We can wait a couple of days and if nobody
shows up, you do it.

[wking]

On Tue, Mar 17, 2015 at 08:12:51AM -0700, Ivan Gonzalez wrote:

@wking, do you mind if I send out an email to discuss to see if a
new instructor wants to take care of the short sentence one? I think
it's easy enough, given that you posted here most of the relevant
links, and could be a good first PR for someone. We can wait a
couple of days and if nobody shows up, you do it.

Sounds good to me :).

[janepipistrelle]

I'd be interested in doing this :)

[iglpdc]

All yours, @janepipistrelle. Let us know if you need help.

[janepipistrelle]

Okay, I've had a go. If it hasn't worked, I've done something wrong (first time doing a PR here!).

[iglpdc]

Closed by #78.

[wking]

On Tue, Mar 24, 2015 at 06:49:31PM -0700, Ivan Gonzalez wrote:

Closed by #78.

Maybe not. Is there still disagreement about if/where to store more
detailed local docs 1? I'm happy after #78, but that was only part
of the solution for some other participants in this issue.

[iglpdc]

You're totally right! Thanks for catching this. Reopening.

[chendaniely]

A picture to accompany the discussion will show students what bad messages look like and hopefully show them not to do it

https://xkcd.com/1296/
https://twitter.com/chendaniely/status/588826374208618496

[iglpdc]

I'm closing this in favor of #190.