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@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list