[libvirt] [RFC] Toward a better NEWS file
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