Change recommended format for commit messages (no more '#1234 by abc')

I think this is ok. There's a sound technical reason for making the switch. It's *definitely* going to take some community re-training to get them to break this habit. I think a mention of this on the Git instructions page is a very good idea, linking off to further details in the handbook.

I use git commit -m '#1234 by abc: def', which works.
Dries uses '- Patch ...', which is unaffected.
Thank you rfay for noticing this!

Basically we need to remove the second sentence on this paragraph

The issue category indicates whether it is a bug, feature, or task, and should be lower-case. It can be omitted if you are phrasing summaries as explained in the following chapter.

from the current official documentation at Commit messages - providing history and credit, since the full template now is
[issue category] #[issue number] by [comma-separated usernames]: [Short summary of the change].

which will work, but yeah communicate it would be the hard task

Randy Fay made a nice screencast at http://screencast-o-matic.com/watch/cXnIh1IFx which outlines why this is so bad.

Well, given "[issue category] #[issue number] by [comma-separated usernames]: [Short summary of the change]." has been documented since November 2009 as a best practice (and implicitly "approved" by at least 4-5 people who've edited that page since), that definitely seems the way to go.

Ugh. I silently (or not so silently?) "accepted" that alternative syntax, but made sure to explain to people why the first/current without prefix is much better: It implicitly makes sure that your commit message is a proper sentence and makes sense for humans.

That is, because the alternative syntax suggests to have a "bug|feature|task" prefix at the start of the line, but no "Fixed|Added|Changed" at the beginning of the actual sentence/message. Therefore, people most often feel "ok" with just taking over the issue title as is, not even thinking a millisecond about a proper, human-readable and understandable commit message (and changelog entry, since that's identical when following best practices).

When rebasing interactively and I imagine at other times, Git happily and helpfully removes all lines that begin with '#'.

Is there a reason why this happens? It feels odd and scary that git is destroying data. If this is not a configuration option, then what else do we have to prevent?

The reason it happens is Git's comment syntax is "lines that start with #". Because the commit messages start with #, it therefore thinks they're comments, and removes them from the overall squashed commit message. See #6.

I'm not aware of any config options around this, else I'm sure we wouldn't be having this discussion. :) I tried googling, but it's astoundingly hard to find keywords that result in anything remotely useful for this, since you of course can't google for "#" and "hash" is something else entirely in Git.

Does this break historical commit messages, or just new ones via git commit?

Only the new commits should be affected by this. Starting a line with a pound is only a nuisance in interactive commit message edit, which should only happen for new commits / rebasing anyway.

gti ci -m is not affected by this.

This is done. We changed it to "Issue #xxx by..." for simplicity. Documented in the Git handbook.

WTF? Why was the entire page duplicated? (existing) http://drupal.org/node/52287 vs. (git) http://drupal.org/node/1061754

Lots of links throughout d.o are pointing to the existing one, so we better merge the required changes into the original page.

Because the docs are still in flux; we've been focused on getting the migration actuallt done. But if you or anyone else wants to take care of merging them and moving 52287 to the right place, that'd be lovely.

Btw, there's an entire collection of docs issues that still need to be fixed now that we're post-migration: http://drupal.org/project/issues/search/documentation?text=&assigned=&su...

I ran across this today since #363367: Co-maintaining projects links to [#52287] -- should we temporarily redirect 52287 to [#1061754]?

52887 = 403 access denied. so, fixed.

err, what? The existing pages need to be updated, not unpublished. These URLs are linked to from everywhere.

The new duplicate pages need to be unpublished instead.

I agree it's unfortunate to be just unpublishing the old pages. At least we should be adding redirects whenever conceivably possible. Usually it's pretty obvious which new page to be using. That said, I'm fine leaving the old CVS-specific nids as the history of revisions for the CVS way, and just start clean with the new nodes and new nids for the Git way. We just have to ensure all the old links and aliases still work.

In terms of the content of the new pages, sorry I didn't suggest this sooner, but I just came up with it today while I was happily doing Git commits on a plane. ;)

Instead of:

Issue #1234 by xxx

How about this?

#1234: "Mark all as read" in forums. by xxx

We're already used to referring to issues like that (or we should be), and it's less duplication when scanning logs, and less wasted horizontal space for the all-important summary line.

I don't think it's necessarily too late to change this. We're still in a transition period trying out all sorts of approaches to all sorts of things, so the "best practices" are still being discovered. I'll probably just adopt this practice for myself, (along with trying to properly credit authorship for people who contribute patches, even if it does take a tiny bit of extra work on my part and it's not the documented recommendation). But this one seems like something we could all just get behind, and is even less work than the currently documented suggestion.

Thoughts? ;)

Thanks,
-Derek

I'm working on cleaning up the organization of the Git handbook, as described in the issue Proposed reorganization of Git handbook. Having found this issue thread, however, I'm wondering if it makes sense to merge portions of the Git handbook with the larger Contributing Code handbook, so that the new Git documentation isn't buried so deep in the book hierarchy. Perhaps this approach was the plan all along and I just became aware of it.

Once I've had a chance to review more of the Contributing Code handbook I'll work on a proposed outline, which I will post on the Proposed reorganization issue thread.

Thoughts?

On both pages, I updated the info about grn. on http://drupal.org/node/52287 , I commented with a link to the new page.

+1 for dww's suggested #1234: "Mark all as read" in forums. by xxx format in #20.

Total -1 to #20
If you use the release note scripts, you get a link to the issue page, and then you can word the message better than the issue title. I agree with rfay.

@rfay: That's just release notes. It'd be an easy patch to http://drupal.org/project/grn to strip out the [ and ] when giving you the default release notes to paste in.

p.s. Release notes were never intended to be a blind dump of commits. I originally wrote cvs_release_notes as a *helper* function to get you started. If all you want is a river of commit messages, look in version control. Release notes are meant to be curated lists of things humans actually care about when deciding if they want to install a new release. The practice of just running these scripts, dumping the output into the release node and pressing go is (IMHO) contributing to the culture where very few end users seem to ever bother reading release notes, since they're often full of incomprehensible developer noise. ;)

Moving this issue to the Documentation issue queue so that all Git documentation issues are in one location.

I think the documentation issue here is closed. http://drupal.org/node/52287 is the authoritative page now and as far as I can tell, the major concern, NOT beginning commit messages with a #, has also been addressed.

If the format of these messages, which affects the community practices at large, is still in question by someone here, can they launch a discussion on G.D.O. where it will receive wider attention? A new issue in the queue can be opened if/when there's consensus for change.

For clarity, I meant the Git team group at http://groups.drupal.org/drupal-org-git-team

Okay, posted: http://groups.drupal.org/node/140309