Re: Is it time to drop ChangeLogs?

[John Wiegley]

>>>>> Lars Magne Ingebrigtsen <address@hidden> writes:

> And I think this is essential input. We are alienating contributors by
> insisting on our weird (ok, "unusual") format of the meta data of the
> patches.
>
> The ChangeLog is useful for some of us. But I would contend that its
> usefulness doesn't trump all the contributors we have discouraged by
> insisting on our quite singular submission format.

Thank you, Lars, you have pretty much summed up my own concerns.

To summarize several of the points in this thread so far:

  - First, and most importantly, we have significant contributors who rely on
    and enjoy the ChangeLog file -- even if there are others, and potential
    contributors, who dislike it.

    If people doing the "real work" are using this file, we should keep it. If
    they want to maintain it as a separate file in Git, we should let them.
    Even if it costs time to maintain it, or explain its necessity to
    newcomers, it's worth it to support those who do the lion's share of the
    work.

    However: once this situation changes, we should revisit the issue. I am
    prepared to drop separate ChangeLog files (generated or not) the moment
    our primary developers say they no longer need it.

  - The ChangeLog format helps to structure commit messages.

    I like this point, and agree that it sets a "bar" for commit log content.
    Whatever helps us raise the calibre of our commit messages makes sense to
    me. However, if we ever find that we're not reading that data while using
    vc-region-history or some other tool, we should revisit this point.

  - Commit messages cannot be edited.

    This is an area where "git notes" could, in fact, help. The idea is not
    that we use git notes for every commit, to provide ChangeLog data, but use
    them to "amend" commit log messages. That way, when generating the
    ChangeLog for release, a git note can override a commit message,
    correcting what appears in the final ChangeLog.

    Using git notes in this way should almost entirely eliminate its merge
    issues, and we'd be using it for its intended purpose: notes on specific
    commits.

In summary, I see two viable paths before us:

  1. Go back to the old way of doing things, using a separately maintained
     ChangeLog file. As long as that's what our main contributors want, I
     believe it's what we should do. Even if we lose some new contributors,
     we should show support for those devoting the most time to our project.

  2. At some future date, should the main contributors no longer rely on or
     want a separate ChangeLog file, we should:

     - Remove ChangeLogs from version control.
     - Require ChangeLog format entries in the commit message, as long as it
       helps us and improves the quality of contributed commit messages.
     - Employ some mechanism, such as git notes, to amend incorrect log
       messages when generating metadata for the release tarball.

Our present mechanism, of maintaining a generated file under version control,
is currently agitating some of our core contributors, nor does it free us from
ChangeLogs. Rather, it's a compromise alternative that includes some of the
worst aspects of both options (e.g., inability to edit commit messages; merge
problems with ChangeLogs; annoying primary contributors; needs tooling to
handle the generation).

That said, I want to make sure that we're actually hearing from all our "core
contributors" in this discussion. Can I hear from some of the other large-
scale contributors? For the sake of argument, here is everyone who has made
more than 500 commits in the past five years (git shortlog --since 2011):

    4467    Glenn Morris
    3582    Paul Eggert                   #2
    2543    Eli Zaretskii                 #1
    1822    Stefan Monnier                #2
    1062    Chong Yidong
    759     Michael Albinus
    675     Lars Magne Ingebrigtsen       #2
    653     Dmitry Antipov
    639     Juanma Barranquero

If there are others who have only recently become highly active, please pitch
in also.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

signature.asc
Description: PGP signature