Re: [libvirt] [RFC] Toward a better NEWS file
On Wed, 2016-10-19 at 18:22 -0400, John Ferlan wrote:
I really think we should do something - especially to be able to
describe what's new, what was added when, etc. beyond what DV culls out
of the existing commits.
Whether the mechanism is some news.html.in or features.html.in or
something else is fine. I don't think we wait until the end of the
release to update. Manually going through patches and matching up to
cover letters by one person for some releases will be easy, while for
other releases it will be an arduous task. That becomes a bottleneck on
one person and could be a time consuming task.
I think all those taking part in the discussion now agree
that it would be better to simply make updating news.html.in
part of the code submission process. That way the entry is
going to be reviewed along with the code, and the work is
spread much more evenly during the release cycle.
Some minor editorial work would probably still be necessary,
or at least welcome, during the freeze to massage the end
result, but the worst case scenario becomes that we ship a
NEWS entry that's not quite as polished as the previous ones.
I think we can live with that :)
I'm confident that, while at first the output might be
sub-par, over the course of a few release we will develop
a "feel" for what category of changes are NEWS-worthy, what
kind of wording is better used to describe a new feature, and
so on... As a result, the quality will improve substantially.
I was thinking after KVM Forum it would be nice if we had some way
to
make it more "obvious" when new features were added and when along with
git commit id link and/or a link to the archives discussing the change.
Makes it easier to find when something was added and get a sense for any
discussion. Something that could be linked off the front page somehow
and updated as the new features are added. Something PROMINENT that
people won't MISS. I wasn't sure about the best way to do that and well
didn't want to take on the task of going through history either. Say
nothing about the task of chasing, editing, etc. possible responses to a
call for NEWS. A task which thankfully you will take on - that's free
beer at every KVM Forum for you from those that don't want to be "it"!
Adding in non trivial bug fixes is nice, especially when we could link
them back to a feature that was added so that someone downstream or up
the stack could use that information to help determine why something
isn't working the way they thought it should be. Using entries that
provide bugzilla pointers would be good too. Still what criteria do we
use for trivial-ness?
What you're describing, while definitely an interesting
concept, is probably out of scope for the NEWS file due to
the sheer amount of metadata involved.
At the end of the day, the source of truth for all changes
to libvirt (and any other project) is going to be the git
log, and the NEWS file shouldn't aim to replace that; instead,
it should provide a high-level and non-comprehensive summary
of the changes made during a release cycle.
Think of it this way: the NEWS file should be an interesting
read for basically 100% of people who install libvirt. Those
who are looking for very specific information, such as a
potentially obscure bug being finally fixed, are probably
best served by the full git log anyway.
One last thing: my proposal only applies to changes made
*going forward*. Nobody's going through 10+ years of libvirt
history and come up with NEWS entries for them ;)
Reviewers will have to remember to ping/remind on
needing to describe/summarize things (that could be in cover letters
found in the archive) if we decide to take the path of having each
commit provide the news update.
Having everyone update the news as changes are being made is another
possibility, but when things get busy (especially at release end) -
dealing with the merge conflicts of the news file will always be a pain.
Plus what about those with push capabilities that don't update (or
refuse to) the news...
Merge conflicts might end up being annoying, but at least
resolving them is going to be trivial.
Catching changes that are NEWS-worthy but don't update
news.html.in is a job for the reviewer, and we're just going
to get used to it in due time :)
--
Andrea Bolognani / Red Hat / Virtualization