On 10/19/2016 07:53 AM, 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 And hope (the quick list that comes to mind): 1. They are paying attention 2. Decide to do so in a timely manner 3. They're not on vacation 4. They're not unwilling to do it 5. They're not "too busy" doing something else "more important" > > * 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. There are those of us who will have a hard time with "short" and "one-three sentences" while there are others that would summarize their changes as "" or "fixed some bugs". Just go through recent history and look at the cover letters and commit messages for examples. > > 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 Not review potential speling and grammer issues ;-) that someone will come along and want to fix some day? Would the fix be newsworthy? (facetiously said of course just in case). > > * 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. > I really think we should do something - especially to be able to describe what's new, what was added when, etc. beyond what DV culls out of the existing commits. Whether the mechanism is some news.html.in or features.html.in or something else is fine. I don't think we wait until the end of the release to update. Manually going through patches and matching up to cover letters by one person for some releases will be easy, while for other releases it will be an arduous task. That becomes a bottleneck on one person and could be a time consuming task. I was thinking after KVM Forum it would be nice if we had some way to make it more "obvious" when new features were added and when along with git commit id link and/or a link to the archives discussing the change. Makes it easier to find when something was added and get a sense for any discussion. Something that could be linked off the front page somehow and updated as the new features are added. Something PROMINENT that people won't MISS. I wasn't sure about the best way to do that and well didn't want to take on the task of going through history either. Say nothing about the task of chasing, editing, etc. possible responses to a call for NEWS. A task which thankfully you will take on - that's free beer at every KVM Forum for you from those that don't want to be "it"! Adding in non trivial bug fixes is nice, especially when we could link them back to a feature that was added so that someone downstream or up the stack could use that information to help determine why something isn't working the way they thought it should be. Using entries that provide bugzilla pointers would be good too. Still what criteria do we use for trivial-ness? Reviewers will have to remember to ping/remind on needing to describe/summarize things (that could be in cover letters found in the archive) if we decide to take the path of having each commit provide the news update. Having everyone update the news as changes are being made is another possibility, but when things get busy (especially at release end) - dealing with the merge conflicts of the news file will always be a pain. Plus what about those with push capabilities that don't update (or refuse to) the news... OK - so that's more than my 2-3 sentences worth! John -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list