[meta] Use the Git commit message format from AngularJS

+1 for this. You can't read core/contrib commits and know what happened. Putting issue number and credits at end is useful. If not even pushing commit credit mentions to new line so it isn't part of the main summary.

When I was working on a Drupal SaaS and having to review git logs of projects we used to see incoming changes it was near impossible to do a simple grok of the commit list.

EDIT: It'd be nice to also compare AngularJS style to other projects.

> The type of change is not included. Bugfix? Or new feature? Or cleanup? Or documentation?

That's not correct. The current commit message standard requires the first word of the description to a verb which tells you that, usually one of 'Fixed'/'Changed'/'Added'.

Now since d.org added the JS that produces the git command for you, that's mostly not been happening, because the JS uses the issue title to create the commit message description, and people aren't bothering to edit what's suggested.

+1 for this suggestion. And also +1 for Matt's suggestion. Instead of putting everything inside the commit summary, few things can be put inside the commit description.

Like this:

fix(phpunit): set SIMPLETEST_USER_AGENT every 5 s

Issue #2771547 by Lendude, klausi, dawehner, alexpott, pwolanin

More info:
- In Browser and FunctionalJavascript tests SIMPLETEST_USER_AGENT cookie needs to be set every 5 seconds

Commit message based on this template:

Capitalized, short (50 chars or less) summary

Issue #NUMBER by CREDITS

More info (optional):
- Info 1
- Info 2

We can then program the Bot to parse the third line of commit and give credits to the user.

This way the commit summary looks cleaner.

Reference:
- http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
- http://chris.beams.io/posts/git-commit

+1 for this suggestion. Drupal could extend the types or adapt to what fits best since these are flexible and this opens up possibility for a lot of good things like using Semantic relaease for managing releases on github, using clog cli for automatic CHANGELOG generation (also used by angularJs both 1 and 2 and many other frameworks) and a number of other tools that can make good use of such a commit style.

great suggestion!

This kind of rearrangement would be very useful, especially given how http://cgit.drupalcode.org/ truncates the commit messages.

Not as sure about burying useful information in the description -- most tools don't really access that.

I think this is an interesting idea. Machine-parseable commit logs have lots of potential applications. But I think it needs more discussion as I'm not sure the exact AngularJS format is right for us.

In particular, I'd like to see the issue number much closer to the front of the message.

I'm also really not keen on the commit message running to multiple lines: same as #8, for more detail there's the issue, the code comments, and the change record.

+1 for having a detailed commit message spanning multiple lines.

+1 for the detailed message but the [Short summary of the change] should come in start instead of the credits

Note there's a lot of prior art on revamping commit strings at #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers, though based on Linux's template rather than Angular's.

+1 to the detailed commits too: when you're offline, the commit messages are often all you get to have an idea of what a commit is about; not everyone is constantly online.

-1 to removing the Issue number from the first line: when browsing comments, finding the issue# in a well-known place makes it easier to go to it. If we start using longer summaries, multiple issues might end up being mentioned, and we would lose the "reference" aspect of the issue# in the one-liner comment on top of the issue.

OK if this is about the single line format I am not in favor. I don't like this format. What I don't like about it:

• It starts with the issue type. This is first of all not very important, I wouldn't put it at the front.
• I don't like the terminology they use for the issue types. Especially not "feat", "chore" and "test". If we are doing this we should use the names we are familiar with: "Bug", "Feature" and "Task".
• The "scope" is unneeded too. This is just noise. If you want to find which commits belong to a particular subset of core you would use the tools that git provides for it (i.e. git log -- core/modules/node). It is not necessary to mention this in the commit message, and especially not in the first line of the commit message.
• I don't like that the issue type and scope are right next to each other without a space in between.
• I especially don't like that the issue number is behind the short description. To me the issue number is the most important part of the commit message. It should be right at the front. Putting it at the back will just increase the chance to have it cut off from certain output formats like git log --oneline. Keeping it at the front also makes it line up nicely. I would drop the current "Issue #" part from it, only keeping "123456".
• For me personally the long list of contributors to a commit does not strictly need to be mentioned in the first line of the commit message. But we can only get rid of it once we decide on a multiline format.

To me the AngularJS format seems badly thought out and not suitable for us. -1

If we are going towards machine parseable data we should not cram it in the first line of the commit message.

My proposal:

123456: (bug) In Browser and FunctionalJavascript tests SIMPLETEST_USER_AGENT cookie needs to be set every 5 seconds (by Lendude, klausi, dawehner, alexpott)

#1282040: Add support for reading git-notes

Using `git notes` for doling out real contribution credit

This doesn't have the benefit of resolving some of the bigger problems we currently have with our commit messages, like #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers does, it just reformats the string to add two meta data items to the commit message and make them more prominent than that was previously displayed. -1 for me.

I think we should consider these issues together, the reworking of the first line, determining the format for commit credit, and hashing out the possibility of a multiline commit message. It is very likely that each of these issues influence the other.

Ideally we could work out a good format that satisfies all three and then make a single announcement for the new format. Otherwise we risk that people will have to learn a new commit message format three times in a short period of time.

@pfrenssen: Your proposal would definitely be an improvement, but having issue numbers without leading "#" is not used anywhere else. I would rather stick to existing standards instead of inventing our own.

I'd really love to have the issue number in front, and I'm not alone with this desire, @joachim also mentioned a preference to have it close to the front in comment #9. The comment of @fgm in #15 also indicates that the issue number is important to him.

I dropped the # because a line starting with this symbol is regarded as a comment by Git and is ignored. I would still be OK with `Issue #123456: xxx` though.

Issue number at the front: An issue number does not give you any information when trying to understand a message. It is very useful to look something up, but a human cannot make any sense out of the number alone. It should definitely be there, but in the beginning it is just something a human needs to read over to get to the actual message contents. That's why you see issue numbers on Github or other places always at the end.

Well no, I think the issue number is the most important thing in the message, and this is due to our particular patch based workflow. If I look at a commit message I mostly do this because I want to know the issue number. I think for as long as we are going to keep committing huge kilobyte sized patches with the necessary background information spread across hundreds of comments in an issue, then the issue number is the thing you really care about :)

Another problem: the messages have a different length. With the AngularJS standard it will look something like this in git log:

####### <actual issue number here> #####
########################### <actual issue number here> #####
## <actual issue number here> #####
########### <actual issue number here> #####
############# <actual issue number here> #####

;)

Terminology of issue types: I would not invent a Drupalism by using our own types. The proposed types are used in many projects and give you a uniform experience when looking at the git log.

We've been using them for 10 years so our standard is as good as anyone else's, and it is better for us since it matches what we use in the issue queue.

I also think that there is no such thing as an "uniform experience", but there is common terminology:

• Number of issues on Github using the word "Chore": <100000
• Number of issues on Github using the word "Task": >1000000

"Chore" is not the standard term at all as you can see.

So for a human it is very hard to read multiple lines of the git log because you have to constantly scan the line where the message begins. That gives me real headaches when I want to get an overview.

This is exactly why I want the issue number in front, then the message, then the commit credit in the back. Then everything is as well aligned as we can make it.

And git log -- core/modules/node fails pretty badly when you move files and directories around, git does not properly follow it.

I have a little tip for you that you will find very useful :)

$ git log --follow

What I also find a really strong argument is that putting the issue number at or near the front is a standard that is widely adopted by other projects. Here are some examples:

• Symfony: "bug #20428 [TwigBundle] fixed template root path (fabpot)"
• Yii: "Fixes #12939: Hard coded table names for MSSQL in RBAC migration"
• Django: "Fixed #27438 -- Added the diffsettings --default option."
• Mozilla Firefox: "Bug 976073 - Part 2: Modify errors from try server, r=jdm"

I like the format from Symfony, that has most of the things we want, including commit credit.

Git doesn't track folders, you need to use actual filenames, then it works fine:

git log --follow -- core/modules/node/node.module

Goes all the way back to:

commit 805107cd2202ddee66c4743e43804a3069508f29
Author: Dries Buytaert <dries@buytaert.net>
Date:   Mon Apr 2 15:54:37 2001 +0000

    Commiting my work of last Sunday:
[...]

> Git doesn't track folders, you need to use actual filenames, then it works fine:

Thing is, our modules and components are folders, not files...

The idea of having formal names for each component or module, that's machine-parseable, is growing on me :) But we'd have to be REALLY strict about it when making commits, otherwise it's just adding not-quite-human-readable junk to the commit log. (I am wary of this because of how lax everyone is about our existing commit message format. This has been especially bad since d.org started suggesting commit messages, which means the convention of starting them with Fixed/Changed/Added has totally gone out of the window.)

> Another problem: Currently the beginning of our git commit messages lines has a different length depending on the number of contributors.

+1 to the first portion of the message being fixed length, or nearly fixed length. (Issue numbers are going to be 7 digits for a while, but there are still older issues getting fixed....)

I don't think the AngularJS format is right for us. I think we're going to have to invent a Drupalism, though maybe one that's concocted from existing ideas.

Well if we really want to borrow a format from another project we could take the format from Symfony:

type #123456 [component] short description (contributors)

Examples:

• bug #2771547 [Render API] Link title double escaping in Link::preRenderLink (kgoel, ifrik)
• feature #123446[outside_in] Create Outside In module MVP to provide block configuration in Off-Canvas tray and expand site edit mode (jessebeach)
• docs #123456 [menu_ui] Incorrect summary line for menu_ui_form_node_type_form_validate() (emma.maria)
• task #123456 [symfony] Update symfony-cmf/routing to 1.4.0 (jensimmons)

This has all the parts from the AngularJS one, doesn't have the awkward formatting with the missing space, has the issue number in front, and is more easily machine parseable than what we have now.

But as I said in #23, I think we should fix all our commit message problems at once. Otherwise we would now introduce a new one-line format, and then a bit later change it again to move the credits to a multiline format for #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers.

The TWG was asked to provide input into this issue (over at #2809773: Provide feedback on changing our git commit message format). We discussed the issue during our meeting on January 31st, 2017, and have the following comments:

1. We recognize the value in a proposed change to the commit message format, given the limitations outlined in the issue summary; and considering that today's format is largely influenced by legacy constraints inherited from the CVS days.
2. However, we also acknowledge that a change to the commit message format has wide-ranging technical implications, in that any tools that look at our git logs (including drupal.org tools) would not only require code changes, but would also require additional functionality to be able to detect between the two formats in order to maintain historical compatibility.
3. There are multiple open issues regarding potential changes to the git commit format, including #2811033: Discuss if git commit messages should be multiple lines, #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers, #1282040: Add support for reading git-notes, and this issue.
4. There is a strong preference for a single adjustment of the git commit format (as opposed to one for the single line format, and a later change for the multi-line conversation), given the complexity this would introduce into the aforementioned tools.
5. While this issue proposes adoption of the AngularJS format, it is not clear whether there has been any research or discussion into other alternative formats. While some may argue the AngularJS is an improvement over our current formatting, the TWG would be interested in a wider body of research prior to implementing any change in the commit message format, illustrating the strengths and opportunities this proposed format provides us over other non-Drupal options which may or may not have been considered. Discussion demonstrating evaluation of this proposal against some of the points raised in some of the more historical conversations regarding the git commit format would also be beneficial.
6. Given the potential scope of implications of this proposed change, the TWG would prefer to see a wider range of community participation in this discussion prior to defining an official position. Of significant note, Drupal Core committers and the Drupal Association Staff are two groups which would be significantly impacted by any changes to this policy, but neither role appears to be strongly represented in this particular discussion (whether advocating for or against the proposed change).

> the TWG would be interested in a wider body of research prior to implementing any change in the commit message format, illustrating the strengths and opportunities this proposed format provides us over other non-Drupal options which may or may not have been considered.

I agree that we should widen the discussion. Not just to consider a list of existing formats, but to try to determine what we want from a commit message format.

A quick and incomplete list of questions we should consider:

- which elements are the most important?
- which should have placement priority, either at the start or the end of the line?
- how important is it to use an existing format rather than devise something?

Then we can look at both existing formats and new ones and sum up which criteria each one satisfies.

bumping back to the front after 6 years. Part of our needs review queue.

Sadly, since we have MR merging built into d.org, hardly anyone uses even our existing commit message format!

That's simply not true, if you use the UI on drupal.org it uses the suggested commit message. Sure, some people don't follow that, but they also didn't before merge requests were a thing.

Plus, this is a core issue, where everyone follows the current standard.

As nod_ brought up in slack does this belong in the idea queue?

> That's simply not true, if you use the UI on drupal.org it uses the suggested commit message.

I can't find it, but the standard for the format at one point was that the description should begin with one of Fixed/Added/Changed. The d.org UI gives you 'Issue #2802947: ISSUE_TITLE' and so nobody uses the first verb any more.

Added/Fixed/Changed was promoted for a while by a group of people (sun being one of them IIRC) that created the recommend commit message guideline for contrib maintainers. It was never actually used by core. Before "Issue #NUMBER" was used it was just "#NUMBER", the switch to the Issue prefix happened as part of switching Git, because starting a commit message with # caused problems when editing them.

The first commit to use the current format was twelve years ago:

* 6dabf4fc47 - Issue #1087092 by danillonunes: Fix documentation for drupal_map_assoc() function (12 years ago) <webchick>

In other words, it has been like this for a very long time and has nothing to with merge requests, if you want to blame something then blame Git, but even before that it wasn't what you think it was :)

For this core repository I think the ship has sailed, most likely possibility to change the commit message format would be: #3220688: [policy] Use conventional commit format

For me this is won't fix at this point I don't see the value. It would also break many scripts relying on the current format for not much benefit.

Maybe the release managers want to change how they manage release notes, so tagging accordingly

The credit system will not rely on commit message so there is no need to change the commit message format for this purpose see #3327584: New contribution records system

Sorry too soon

There are also some related issues in the drupalorg project queue, e.g. #2955276: Automatically generate release notes when new release is tagged.

The release managers have discussed this issue. No one preferred this particular format. There was also concern that an implementation would be disruptive by breaking a decade of log parsers. Although, the latter is likely true for any change to the commit message.

Other ideas can continue to be discussed in the earlier issue, #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers

Therefor, we all agree with @nod_ that it it time to close this issue.