[libvirt] [RFC] Toward a better NEWS file

[Andrea Bolognani]

Hi,

there's an idea that has been kicking around in my head for
a while, and I'd like to share it with the list to gather
some feedback before I forget about it :)

Right now, each entry in our NEWS file contains what is
basically the output of

  git log \
      --pretty=oneline \
      vX.Y-1.0..vX.Y.0

with the commits organized somewhat arbitrarily into a bunch
of sections with partially overlapping scopes.

I believe the current form is less than useful, as it is too
detailed for end users and distro packagers, who only care
about the high-level user visible changes, and not detailed
enough for developers, who are always going to refer to the
proper git log anyway. Moreover, we ship a ChangeLog file
that contains very detailed information already.

Ideally, the NEWS file would contain a summary of notable
changes (new APIs, significantly improved features, etc.)
laid out in an easy to digest fashion, such that people who
are not knee-deep into libvirt development can grasp them
and hopefully get excited about upgrading to our latest and
greatest release :)

Of course, it would take an insane amount of time for any
single one of us to turn the git log into such a document,
and the result would still be sub-par because we simply
can't expect anyone to have full insight in every single
change to the project.

My solution for this is to ask the people with the most
knowledge of the changes - the authors themselves!

The workflow I'm envisioning would look like this:

  * DV, at the same time as he announces that libvirt has
    entered freeze, will put out a Call for NEWS and ask
    people who have contributed code to the upcoming release
    to post a summary of their changes

  * the authors will go over

      git log \
          --author=$(git config user.email) \
          vX.Y-1.0..master

    and come up with a short (one-three sentences) summary
    for each of the changes, if they are notable. Commits
    that are part of a larger series would not be described
    on their own: a short summary of the series would be
    used instead, akin to the one you would put in your
    cover letter.

    To give a practical example: I've mostly been busy with
    reviews this cycle, but if I were to go over my commits
    since v2.3.0 right now I would write something like

      * Bug fix: don't restart libvirt-guests.service when
        libvirtd.service is restarted

    for commit 2273bbd, and omit both 61e1014 and a0da413 as
    they're neither notable enough on their own, nor part of
    a larger series: we'll always have a "various bug fixes
    and improvements" bullet point in a NEWS file entry to
    take care of that kind of small cleanups and improvements.

  * the authors would post the resulting summaries to the
    list. We could simply post them as regular patches to
    docs/news.html.in (potentially without requiring review
    before pushing them), or post them as plain text and have
    someone collect them and prepare a single commit

  * DV will tag the release and push the tarballs, and
    everyone will be able to enjoy the NEWS file :)

Some light editoral work might be needed throughout the
process, eg. fix typos or post one or two reminders during
the freeze: I volunteer to take such tasks upon myself.

I'm looking forward to feedback about this idea, especially
from people who might be part of any community where anything
like this is already happening.

-- 
Andrea Bolognani / Red Hat / Virtualization