Re: [libvirt] [RFC] Toward a better NEWS file

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/ :| -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list