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

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.