On Wed, Oct 19, 2016 at 12:58:55PM +0100, Daniel P. Berrange wrote:
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 like the idea, but going back to my patches with sometimes as less as 2-day notice, and also requiring bunch of people to do it at the same time feels weird.
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.
I was thinking something along the lines of this ^^. With the exception that it would be a file that gets used by DV at the time of release and then cleared for the next one. Traditional NEWS file works for me too, though.
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
Attachment:
signature.asc
Description: Digital signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list