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.

On Wed, 2016-10-19 at 12:58 +0100, Daniel P. Berrange wrote: > 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'm strongly against adding more generated files to the repository; if anything, we should have *less* of them[1]. But if we required the source file, docs/news.html.in, to be updated along with notable changes instead, I would be all for it! :)

[1] Hello, HACKING!

--  Andrea Bolognani / Red Hat / Virtualization -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list

On Wed, 2016-10-19 at 15:19 +0200, Martin Kletzander wrote: > > > 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'm strongly against adding more generated files to the > > repository; if anything, we should have *less* of them[1]. > >  > > But if we required the source file, docs/news.html.in, to > > be updated along with notable changes instead, I would be > > all for it! :) >  > I understood it like this: >  >  - stop generating NEWS file >  - populate NEWS file with notable features/bug-fixes along with the >    changes themselves >  - use NEWS to make nice news.html Why would we build news.html from NEWS when we already have a perfectly fine way to build both NEWS and news.html from news.html.in?

> > [1] Hello, HACKING! >  > Yeah, that's a problem, we want the plain-text HACKING to be there, but > we want the stuff to be on the web page too.  This could be fixed by > making hacking.html.in generated from HACKING and changing HACKING to > use some kind of plaint-text friendly formatted text (org, rst, md, …) > in order not to lose the metadata ;) I was discussing this offline with Ján just yesterday. IMHO the way forward is to basically   * stop building HACKING from hacking.html.in   * move README-hacking to HACKING   * (optionally) rename hacking.html.in to     contributorguidelines.html.in - that's already the title     of the document anyway   * improve the contents of both HACKING and hacking.html.in I think HACKING should contain just the information required to get from a fresh git clone to a buildable source tree, eg. the extra steps you wouldn't have to take if you were building from a release archive. And README-hacking is basically there already.

--  Andrea Bolognani / Red Hat / Virtualization

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(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list

On 19.10.2016 19:58, Daniel P. Berrange wrote: > On Wed, Oct 19, 2016 at 01:53:41PM +0200, Andrea Bolognani wrote: >> Hi, >> >> <snip/> > > 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'm up for this one. While introducing a new feature (which touches a lot of code anyway) we will just update one file more. I see no problem with that. Having to provide news per developer later, trying to recall what have I done, might be harder. Therefore NEWS (or news.html.in) should be updated among with a major change in the code. But let me also provide another reason why this is important (thank you Andrea for starting the thread). I spoke to people who test our software and sometimes they are just lost with current form of NEWS. It is very hard for them to even understand new features in the release so that they cannot really update their test cases (or they do so partially). If we make NEWS format more readable it will be easier for them to implement new tests and subsequently it will increase quality of our project.

On 19.10.2016 19:58, Daniel P. Berrange wrote: > On Wed, Oct 19, 2016 at 01:53:41PM +0200, Andrea Bolognani wrote: >> Hi, >> >> <snip/> > > 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'm up for this one. While introducing a new feature (which touches a lot of code anyway) we will just update one file more. I see no problem with that. Having to provide news per developer later, trying to recall what have I done, might be harder. Therefore NEWS (or news.html.in) should be updated among with a major change in the code. But let me also provide another reason why this is important (thank you Andrea for starting the thread). I spoke to people who test our software and sometimes they are just lost with current form of NEWS. It is very hard for them to even understand new features in the release so that they cannot really update their test cases (or they do so partially). If we make NEWS format more readable it will be easier for them to implement new tests and subsequently it will increase quality of our project. Michal -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list

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.