All commits must be trackable to an Issue about omr

[charliegracie]

I think this is a good thing to do. I would suggest we ask that commit comments follow a format similar to this:

Simple Description
Detailed information if required

Issue: #
Signed-off-by: First Last

[DanHeidinga]

Overall, I agree with this approach but expect that trivial changes (spelling fixes, etc) can be done without an issue.

Doing a bit of reading, in particular [1], indicates:

Unless you are making a rather minor change, it is generally a good idea to file an issue on the appropriate bug tracker, explaining your idea before writing code or submitting a PR, especially when introducing new features.

which is the kind of wording I think we should adopt.
[1] https://contribute.jquery.org/commits-and-pull-requests/

[alin00]

It sounds like we don't want to use the github feature of closing issues via commit comment, right?

It's helpful to put the Issue # in the first line of the commit comment so that you can get a quick overview using "git log --oneline".

I suggest tweaking the comment template to this:

Issue #nn Simple Description
<blank line>
Detailed information if required

Signed-off-by: First Last <email>

[alin00]

I don't mind not having an issue for truly trivial patches, but I think any multi-commit piece of work should be tied together by having an issue number which is referenced in the commit comments.

I don't care whether we use an issue number or pull request number, but a pull request number doesn't seem to work well since it doesn't exist until after you have made a bunch of commits and created the pull request. You would have to edit every commit on the pull request branch to add in the pull request number.

[mstoodle]

How about:

#n Short, simple summary

Detailed information if required

Signed-off-by: First Last <email>

That's simple, puts the issue number (I'll make sure its described as the Issue number and should not be the pull request number) into every commit title. I suppose the recommendation would be to follow the same form in the pull request, which at least makes it easy to describe.

If no additional concerns, I'll commit this change tomorrow.

[alin00]

Looks good to me.

[charliegracie]

+1

[mstoodle]

Amusing: # starts a comment so the first line cannot start with that. D'oh!

I recommend we give up on a "rigid" positioning of the issue text and just say the title has to have #N in it somewhere.

[DanHeidinga]

+1

[alin00]

As long as we can write tooling that finds it (and doesn't get too many false hits), fine with me.

[charliegracie]

Hmmm I made some commits today that started with # and it appears in the text for the commit. You are right though that lines starting with # are supposed to not show up.

I guess I should go update my commit messages.

[mstoodle]

The suggestion was to specify that "#n" needs to appear somewhere in the message. That's enough for github to find the link.

I see your commits on #64, Charlie. How did you do that? When I tried it, git commit failed saying my commit message was empty (and it actually was :) ). The only difference I see is that your commits also had detailed comments whereas mine did not. No idea why it didn't treat your title line as a comment.

Weird. But your commit message still fits the template as suggested :) .

[alin00]

I agree with @charliegracie on this:

If we are not rigid then people will not do it ...

[mstoodle]

The rigidity comment was only about the positioning...

[alin00]

http://stackoverflow.com/questions/2788092/start-a-git-commit-message-with-a-hashmark

The rigidity comment was only about the positioning...

Understood. I prefer to have a clear template with clear positioning. I prefer going back to one of the older proposals of starting the abstract with "Issue #nn" or "Fix #nn". However, I'm willing to compromise on positioning and prefix if everyone else prefers otherwise.

My hard requirements are:

1. All commits have the same comment template, with no conditional parts that require judgment to fill in.
2. It is easy to find all commits for a particular issue number, and construct a short summary of the commits. e.g. using git log --grep='#25' --oneline

[alin00]

It's quite possible for a commit comment to refer to other issue numbers, so I prefer having a keyword to identify the issue most relevant.

[alin00]

We've settled on Mark's most recent proposal.