Humble proposal : change format of commit messages

[Dimitri Merejkowsky]

Hi there,


Currently, the vim commit messages on github look like:

> patch 8.0.0142
> Problem:    Normal colors are wrong with 'termguicolors'.
> Solution:   Initialize to INVALCOLOR instead of zero. (Ben Jackson, closes #1344)


A title with the patch number, a line for the problem, and a line for the
solution.

This is nice because the patch number is easy to read, and the commit message is
easy to parse.

However, many git tools assume that there's a blank line between the so called

'title' and 'body' of the commit messages.

So I suggest instead to negate the 'problem' part, keep the  solution' part
as a body, and add a blank line.

Thus the commit message would look like:

> patch 8.0.0142:  Fix normal colors when used with 'termguicolors'.
>
> Initialize to INVALCOLOR instead of zero. (Ben Jackson, closes #1344)

I'm aware this may break existing scripts relying on vim patches message format, but
this convention is widely used (git itself, the kernel, and everything written
by Tim Pope[1]...), so I believe it's worth it.

Note that I'm _not_ suggesting any other changes in vim development process.

I simply think that this would allow any fork of vim using a different process
(based on pull requests, for instance) a little easier when trying to backport
complex vim features, as seen for example here[2].


[1]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[2]: https://github.com/neovim/neovim/pull/5771

Cheers,

Dimitri Merejkowsky

[Daniel Moch]

On Wed, Jan 04, 2017 at 08:43:01PM +0100, Dimitri Merejkowsky wrote:
> So I suggest instead to negate the 'problem' part, keep the solution' part
> as a body, and add a blank line.
>
> Thus the commit message would look like:
>
> > patch 8.0.0142: Fix normal colors when used with 'termguicolors'.
> >
> > Initialize to INVALCOLOR instead of zero. (Ben Jackson, closes #1344)

One issue with your proposal is that it creates the likelihood of the
'title' line being longer than it should be (you refer to tpope's
article, where he suggests keeping it to 50 characters or less). In any
case, we're talking about guidelines and I don't see any reason to ask
Bram to change the way he works.

--
Daniel Moch
dan...@danielmoch.com
https://about.me/danielmoch

[Nikolay Aleksandrovich Pavlov]

I know no reasons to keep it 50 characters nowadays: tpope refers to
80-character-wide terminal and I never used such for developing and
have no reasons to think other developers deliberately limit
themselves to 80-character-wide terminals on desktop (80x24 terminals
were for old 4:3 screens with big pixels, modern screens are normally
something like 16:9, often bigger and have much, much less pixel size:
this makes 80x24 terminals either use very huge font size or occupy
little space on screen). But there is a reason to limit title to 70
characters: after 70 characters github truncates even the title line,
and I also limit commit message body to 80 characters (because it is
default &textwidth; personally I am fine with 110: my terminal is
119+119+(split column) wide when splitted in two parts by Vim or
tmux).

The reason is obvious: everywhere where you see short list of commit
messages (github PRs commit list, github project commit list, thread
titles in the mailing list, some git commands, some github automatic
emails (I mainly see emails of Neovim PRs with ports)) you immediately
see only title line. Seeing just “patch …” here is highly inconvenient
there, this contains almost no information.

>
> --
> Daniel Moch
> dan...@danielmoch.com
> https://about.me/danielmoch
>

> --
> --
> You received this message from the "vim_dev" maillist.
> Do not top-post! Type your reply below the text you are replying to.
> For more information, visit http://www.vim.org/maillist.php
>
> ---
> You received this message because you are subscribed to the Google Groups "vim_dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+u...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Eric Pruitt]

On Thu, Jan 05, 2017 at 07:19:07PM +0300, Nikolay Aleksandrovich Pavlov wrote:
> The reason is obvious: everywhere where you see short list of commit
> messages (github PRs commit list, github project commit list, thread
> titles in the mailing list, some git commands, some github automatic
> emails (I mainly see emails of Neovim PRs with ports)) you immediately
> see only title line. Seeing just “patch …” here is highly inconvenient
> there, this contains almost no information.

I agree that Bram's commit format leaves something to be desired. Let's
say Bram changed the commit format so that the first line was "Fix
$PROBLEM." If we use Git's recommended summary length of 50 characters,
that means the $PROBLEM needs to be at most 46 characters. An adhoc awk
script shows that close to half of the last 1000 commits could fit:

$ git log -1000 | awk '/Problem:/ {
$1 = ""
gsub(/^[ \t]+|[ \t]+$/, "")
t++
n += length() <= 46
}
END {
print "Total:",t
print "Fit:", n
}'
Total: 939
Fit: 437

I suspect a lot more than that could fit because Bram often adds the
author or reporter's name to the end of the messages. If you change the
length to 76 (strlen("Fix $PROBLEM") <= 80), almost all of the commits
fit (note that the above script won't provide an accurate number for
that). Having an initial message with a descriptive commit would make it
a lot easier to do things like using Git's interactive modes for
rebasing and bisecting.

Eric

[Nikolay Aleksandrovich Pavlov]

Why 50 and 80? For github it is better limit titles to 70 characters
(unicode codepoints), I explained why in previous message, also “Fix
$PROBLEM” is not a good message for adding features. It is really OK
to just have $PROBLEM here: anything which is more descriptive then
“patch {number}” is better, though I still would expect something like
commit titles in other projects in which case things like “Normal
colors are wrong with 'termguicolors'” would transform into “Fix
normal colors with 'termguicolors'”: in many cases title will shrink
compared to “Problem: …”.

>
> Eric

[Bram Moolenaar]

Github truncates the title, thus if we put the Problem there we won't
get the whole text. Other solutions would be to have a summary first,
like the README on the ftp site, and then the whole Problem and Solution
as the body.

Not sure if anybody depends on the current text. I can try it out with
the next patch.

--
What is the difference between a professional and an amateur?
The ark was built by an amateur; professionals gave us the Titanic.

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///