[libvirt] [RFC] Toward a better NEWS file

Wed Oct 19 12:56:11 UTC 2016

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 at redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20161019/004aa08e/attachment-0001.sig>