[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. -- 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/ :|
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
On Wed, Oct 19, 2016 at 02:54:06PM +0200, Andrea Bolognani wrote:
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! :)
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
[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 ;)
-- Andrea Bolognani / Red Hat / Virtualization
-- libvir-list mailing list libvir-list@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 03:59:37PM +0200, Andrea Bolognani wrote:
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?
I meant news.html.in of course. But we can be updating news.html.in and keep all the files generated as they are now.
[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.
OK, so you had different plans while I was just thinking how to keep the same things in place but remove redundant duplicates from git.
-- Andrea Bolognani / Red Hat / Virtualization
On Wed, 2016-10-19 at 21:40 +0200, Martin Kletzander wrote:
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? I meant news.html.in of course. But we can be updating news.html.in and keep all the files generated as they are now.
My point is that it's generally easier to generate an unstructured file (NEWS) from a structured source (news.html.in) than going the other way around. Of course we could switch the NEWS file to Markdown or something like that, but then our build process would require yet one more tool. I'm also not sure all of us are as proficient with these pseduo-markup languages as we are with HTML, which is already fairly heavily used in our documentation: speaking just for myself, of the formats you proposed below, I could do Markdown, but ReStructured Text is something that I would have to learn from scratch just to edit this one file, and I don't even know what "org" is :D
[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. OK, so you had different plans while I was just thinking how to keep the same things in place but remove redundant duplicates from git.
I had patches that got rid of the duplicated content in git as far back as a year ago[1], but at the time there was some very reasonable pushback because we still want to provide some direction to people who just cloned the git repository. The proposal above solves all the issues I have with the HACKING file while taking care of the original concerns as well, so I'm quite happy with it :) [1] https://www.redhat.com/archives/libvir-list/2015-October/msg00740.html -- Andrea Bolognani / Red Hat / Virtualization
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@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. Michal
On Fri, Oct 21, 2016 at 10:10:50AM +0800, Michal Privoznik wrote:
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.
Take a look at how we structure NEWS file for gtk-vnc: https://git.gnome.org/browse/gtk-vnc/tree/NEWS We try to give users concise information, ordered by importance That is the kind of format I think we should aim for. 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/ :|
On Fri, 2016-10-21 at 10:32 +0100, Daniel P. Berrange wrote:
Take a look at how we structure NEWS file for gtk-vnc: https://git.gnome.org/browse/gtk-vnc/tree/NEWS We try to give users concise information, ordered by importance That is the kind of format I think we should aim for.
Looks good to me! But we should IMHO really stick to using the HTML file as source and convert it to plain text at dist time, so we can have the same information available both in the release archive and on the website. Shall we give this kind of format a go for 2.5.0, see if it works for us? We could still fall back to the current NEWS format if the experiment doesn't pan out. -- Andrea Bolognani / Red Hat / Virtualization
Hello, I'm quite new in libvirt community so I don't know all requirements which community have but did You know about reno project from Openstack: http://docs.openstack.org/developer/reno/ ? It's used for managing releae notes which are added in git as separate files. Maybe it can be some solution for You also :) -- Best regards / Pozdrawiam Sławek Kapłoński slawek@kaplonski.pl On Fri, 21 Oct 2016, Michal Privoznik wrote:
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@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Fri, Oct 21, 2016 at 12:33:44PM +0200, Sławek Kapłoński wrote:
Hello,
I'm quite new in libvirt community so I don't know all requirements which community have but did You know about reno project from Openstack: http://docs.openstack.org/developer/reno/ ? It's used for managing releae notes which are added in git as separate files. Maybe it can be some solution for You also :)
reno is totally over-engineered IMHO - we don't need to add another build pre-requisite just to manage what is ultimately a simple text file. 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/ :|
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
On Wed, 2016-10-19 at 18:22 -0400, John Ferlan wrote:
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 think all those taking part in the discussion now agree that it would be better to simply make updating news.html.in part of the code submission process. That way the entry is going to be reviewed along with the code, and the work is spread much more evenly during the release cycle. Some minor editorial work would probably still be necessary, or at least welcome, during the freeze to massage the end result, but the worst case scenario becomes that we ship a NEWS entry that's not quite as polished as the previous ones. I think we can live with that :) I'm confident that, while at first the output might be sub-par, over the course of a few release we will develop a "feel" for what category of changes are NEWS-worthy, what kind of wording is better used to describe a new feature, and so on... As a result, the quality will improve substantially.
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?
What you're describing, while definitely an interesting concept, is probably out of scope for the NEWS file due to the sheer amount of metadata involved. At the end of the day, the source of truth for all changes to libvirt (and any other project) is going to be the git log, and the NEWS file shouldn't aim to replace that; instead, it should provide a high-level and non-comprehensive summary of the changes made during a release cycle. Think of it this way: the NEWS file should be an interesting read for basically 100% of people who install libvirt. Those who are looking for very specific information, such as a potentially obscure bug being finally fixed, are probably best served by the full git log anyway. One last thing: my proposal only applies to changes made *going forward*. Nobody's going through 10+ years of libvirt history and come up with NEWS entries for them ;)
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...
Merge conflicts might end up being annoying, but at least resolving them is going to be trivial. Catching changes that are NEWS-worthy but don't update news.html.in is a job for the reviewer, and we're just going to get used to it in due time :) -- Andrea Bolognani / Red Hat / Virtualization
participants (6)
-
Andrea Bolognani -
Daniel P. Berrange -
John Ferlan -
Martin Kletzander -
Michal Privoznik -
Sławek Kapłoński