[libvirt] [RFC] Toward a better NEWS file

[Daniel P. Berrange]

On Wed, Oct 19, 2016 at 01:53:41PM +0200, Andrea Bolognani wrote:
> 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.

Why don't we simply have a NEWS file in GIT, and require that
non-trivial commits or patch series include an update to NEWS,
so the NEWS file gets populated at time the feature/bug fix
gets merged.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|