Bug 370038

Comment 1 Steffen Pingel 2012-02-01 20:32:17 EST

That's a great idea. I think it's time to consider an update of the default template. Besides the increasing popularity of Git the standard Git convention of using Key: Value is reads well, is easy to parse and leaves room for future changes. Of course, the hard part is going to agree on a standard set of fields. 

I would go as far as leaving out task status since in my personal experience I haven't found that to be particularly relevant in the context of commit history Here is my suggestion (${cursor} denoting the default cursor position, a feature that is not yet supported):

pre..  
${task.description}${cursor}

Task: ${connector.task.prefix} ${task.key}
Task-Url: ${task.url}

Comment 2 Shawn Minto 2012-02-02 13:23:39 EST

My concern is that there are existing integrations (old versions of Mylyn included) that rely on the default commit message format to be able to associate changesets with tasks and all of these would need to be updated to support both.

Comment 3 David Green 2012-02-02 13:34:15 EST

I'm in favor of changing the commit message.  I personally like having the task key and summary on the first line (probably because I'm used to it), followed by the URL -- however this is problematic when contributing to projects such as EGit that have their "own guidelines":http://wiki.eclipse.org/EGit/Contributor_Guide#Commit_message_guidelines

The EGit guidelines are problematic since the task key (bug id) is not associated with an URL, which makes traceability difficult since the task id could apply to any repository (of course _they_ know which one they're using, but this is not easily discoverable by tools).

One problem that I see with providing the description first is for bugs where the description contains one or more stack traces.  These (in the case of Bugzilla) can be up to 32,000+ characters, which is not very useful for a commit message.

We could provide a way to register "standard" commit templates.  That way the EGit/Mylyn contribution (for example) could register their commit template, making it easier for people to contribute.  We'd have to put some thinking into how this would work.  Presumably people would want different commit templates setup for different remotes.

Comment 4 Lucas Panjer 2012-02-02 13:46:52 EST

Regarding Git I think this makes a lot of sense. I'm not sure how this would affect other SCMs. Perhaps we need default commit message templates for each Team Provider.

h3. Git specific thoughts:

As Manuel suggests, a variety of Git tooling (by convention) works well when there is an initial line of description followed by a blank lline, followed by a potentially longer description of the change. See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html for some pointers on how the summary line of git commit messages is used in other tools.

I don't necessarily agree with the line length aspects suggested in that article, but having a one line summary would allow a git log view of commits where each line succinctly describes the change that was made. If this line is always pre-filled as the task summary then the log will just be repetitive. For this reason I think it is important for the developer to actually describe the change they made in their commit message. This is especially important when the repository is used or reviewed without access to the associated task data.

The approach of key-value tags makes sense and is already a convention with other Git tools such as Gerrit. Mylyn could later use the ID and URL fields to scan a Git repository to build list of commits related to a task.

I suggest a commit template (for Git) as follows:

pre.. ${cursor} <- you should be writing a one line summary describing your actual change here.

${task.summary}

Task-Id: ${task.key}
Task-Url: ${task.url}

Comment 5 Manuel Doninger 2012-02-02 14:44:12 EST

Just for clarification: I didn't mean to change the default Mylyn template, but the project configuration of the Mylyn plugins itself (the template which Mylyn contributors and committer use). But i don't mind to also change the default template.

Comment 6 Steffen Pingel 2012-02-02 15:03:42 EST

Sorry for hijacking the bug, Manuel. If we change it for Mylyn we should consider changing the default since the change would likely to be an improvement for others as well.

To clarify: the ${task.description} template is the summary of the active task. The name is a bit misleading we can use ${task.summary} for the purpose of discussion (which is also misleading because it gets replaced by the description if there is no summary).

Comment 7 Matthias Sohn 2012-02-27 18:41:58 EST

(In reply to comment #4)
> 
> I suggest a commit template (for Git) as follows:
> 
> pre.. ${cursor} <- you should be writing a one line summary describing your
> actual change here.
> 
> ${task.summary}
> 
> Task-Id: ${task.key}
> Task-Url: ${task.url}

I think adding the task.url adds a lot of redundant information
as most projects use exactly one bug tracker for all their
bugs. Instead we could adopt Gerrit's trackingid configuration [1] also
in EGit in order to enable rendering of hyperlinks for ${task.key} 
displaying only the key.

[1] https://git.eclipse.org/r/Documentation/config-gerrit.html#_a_id_trackingid_a_section_trackingid

Comment 8 Steffen Pingel 2012-02-28 07:11:04 EST

Guidelines:

http://wiki.eclipse.org/Linux_Tools_Project/Git#Commit_messages
http://wiki.eclipse.org/EGit/Contributor_Guide#Commit_message_guidelines

Related discussions:

http://dev.eclipse.org/mhonarc/lists/gef-dev/msg01541.html
http://dev.eclipse.org/mhonarc/lists/platform-ui-dev/msg05180.html

Comment 9 Sam Davis 2012-05-25 13:39:00 EDT

(In reply to comment #4)
> pre.. ${cursor} <- you should be writing a one line summary describing your
> actual change here.

If Mylyn is going to encourage writing commit messages rather than writing comments on a task, it seems to me it would be important for those commit messages to also appear as comments on the task, that people can respond to, and for there to be easy linking from the commit message to the comment (I think we may have this linking already but it is probably buggy). The task should contain all the discussion related to it, and the commit message should be part of that.

Comment 10 Steffen Pingel 2012-07-23 09:57:50 EDT

(In reply to comment #9)
> If Mylyn is going to encourage writing commit messages rather than writing
> comments on a task, it seems to me it would be important for those commit
> messages to also appear as comments on the task, that people can respond to, and
> for there to be easy linking from the commit message to the comment (I think we
> may have this linking already but it is probably buggy). The task should contain
> all the discussion related to it, and the commit message should be part of that.

That makes sense to me and is something that we have discussed as part of improving the traceability story in this Summer of Code project: http://wiki.eclipse.org/Mylyn/Activity_Tracing_For_Mylyn

Comment 11 Steffen Pingel 2012-07-28 07:34:54 EDT

I'm proposing that we set the commit template for all Mylyn projects to the one shown below for the following reasons:

* In most cases we have 1-2 commits per task. Requirements and discussion around the change are tracked on the task so I would like to have a default commit template that is sufficient for that 80% case.
* When needed it's very simple to add additional details around the change below the first line.
* By removing status and prefix the first summary line of the commit should be short to be consistent with the Git line length guidelines in most cases. 
* Leaving the task key in the summary makes it easy to identify related commits when scanning the history where only the summary line is shown.
* The Task-Url key ensures that Mylyn's open corresponding task features will continue to work and will enable future traceability enhancements.
* The Bug key ensures that Gerrit's search integration works. It's redundant with the summary but I would argue that the value outweighs the cost.

pre.. 
${task.key}: ${task.summary}

Bug: ${task.key}
Task-Url: ${task.url}

Comment 12 Steffen Pingel 2012-07-28 07:36:44 EDT

In order to make progress on this task I would like to put the different commit templates up for a vote on mylyn-dev. If you have alternative proposals please bring them forward so we can include them in the vote.

Comment 13 Steffen Pingel 2012-08-06 07:09:47 EDT

Let's vote. Please state your +1 or -1 (including an explanation) for the proposal in comment 11. I propose that we leave this open until September 3 to accommodate for summer vacations.

Comment 14 Sam Davis 2012-08-06 15:27:19 EDT

+1

Comment 15 Steffen Pingel 2012-09-06 23:18:55 EDT

I have set the commit template as proposed in comment 11 for all Mylyn projects.

Comment 16 Frank Becker 2012-11-11 09:19:23 EST

Steffen,

I create review https://git.eclipse.org/r/#/c/8630/ for migrate the commit template can you please review.

I create this because in my environment I did not get the new template format.

Comment 17 Frank Becker 2012-11-11 09:19:29 EST

Created attachment 223434 [details]
mylyn/context/zip

Comment 18 Steffen Pingel 2012-11-11 10:35:00 EST

We decided not to change the default template at this point but configured the new template for all Mylyn projects.