Re: request for your comments on release documentation
On Jun 27, 2013, at 7:24 PM, Miroslav Lachman wrote: > Mark Felder wrote: >> On Wed, 12 Jun 2013 12:49:21 -0500, Hiroki Sato wrote: > > [...] > >>> 3. Is there missing information which should be in the relnotes? >>> Probably there are some missing items for each release, but this >>> question is one at some abstraction level. Link to commit log and >>> diff, detailed description of major incompatible changes, and so >>> on. >> >> I try to keep up with the development and changes in releases as best I >> can and I haven't noticed any glaring omissions over the last several >> releases. I think you're doing a fine job. >> >> Also, is there a reason this isn't a "living" document that can be >> updated as things get MFC'd to STABLE? It would help take load off your >> end and maybe speed up release once the freeze has happened and we begin >> the final grind through release candidates. > > It would be nice if all release related documents (relnotes, errata, hardware > notes etc.) will be "living" after release (in online version) and not > considered as set in stone. There are sometimes missing items which should be > included online as soon as possible, but rarely are. > > For example, I found two issues with OpenSSH in 8.4 release. (bugs or > features, or just incompatibilities with older versions) None of them is > listed anywhere and I think it is really bad, because one issue can cause > sshd not started after upgrade. > > So the online version of these docs should be "living" and updated as some > issues and questions arises on the mailing lists and forums few days / weeks > after release. Additionally, it would be nice if the documentation for beta and RCs was posted before the actual release as well. Just like the OS itself, docs can be "beta" and open for feedback from the community. It's also nice to know about changes before you upgrade a box for testing as well - for example, the jail changes and zfs version bump in 8.4 were something of a surprise for me (I follow -stable, but not much else). If the project wants people to test before release, having a list of changes, major and minor to focus on would probably net the project more useful feedback. I'm also all for the "living" document idea. It seems like the mailing lists always have a few issues that are documented nowhere else because they don't quite merit a ERRATA notice (eg: dhclient/fxp issue). Thanks, Charles > > > On the other hand, FreeBSD has good quality of docs included Release Notes. > (thank you for your work!) > If there is some "man power", some items can be more detailed with links to > other online resources like FreeBSD wiki, but only for some important items. > > Miroslav Lachman > ___ > freebsd-stable@freebsd.org mailing list > http://lists.freebsd.org/mailman/listinfo/freebsd-stable > To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org" ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
Re: request for your comments on release documentation
Mark Felder wrote: On Wed, 12 Jun 2013 12:49:21 -0500, Hiroki Sato wrote: [...] 3. Is there missing information which should be in the relnotes? Probably there are some missing items for each release, but this question is one at some abstraction level. Link to commit log and diff, detailed description of major incompatible changes, and so on. I try to keep up with the development and changes in releases as best I can and I haven't noticed any glaring omissions over the last several releases. I think you're doing a fine job. Also, is there a reason this isn't a "living" document that can be updated as things get MFC'd to STABLE? It would help take load off your end and maybe speed up release once the freeze has happened and we begin the final grind through release candidates. It would be nice if all release related documents (relnotes, errata, hardware notes etc.) will be "living" after release (in online version) and not considered as set in stone. There are sometimes missing items which should be included online as soon as possible, but rarely are. For example, I found two issues with OpenSSH in 8.4 release. (bugs or features, or just incompatibilities with older versions) None of them is listed anywhere and I think it is really bad, because one issue can cause sshd not started after upgrade. So the online version of these docs should be "living" and updated as some issues and questions arises on the mailing lists and forums few days / weeks after release. On the other hand, FreeBSD has good quality of docs included Release Notes. (thank you for your work!) If there is some "man power", some items can be more detailed with links to other online resources like FreeBSD wiki, but only for some important items. Miroslav Lachman ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
Re: request for your comments on release documentation
On Jun 12, 2013, at 11:49 AM, Hiroki Sato wrote: > I would like your comments on release notes for each release. > Although I have been working on editing them for years, the workflow > is still not optimal and sometimes delay of the preparation became an > obstacle for release process. I would like to improve it, but before > that I would like to know what are desired of the contents which > people think. > > Release Notes is just listing the changes between the two releases. > It includes user-visible change (bugfix and/or UI change), new > functionality, and performance improvement. Minor changes such as > one in kernel internal structure are omitted. I always try to keep > these series of relnotes items are correct and reasonably > comprehensive, but this lengthy list may be boring and > technically-correct descriptions can be cryptic for average users. > > So, my questions are: > > 1. What do you think about current granularity of the relnotes items? >Too detailed, good, or too rough? Currently, judgment of what is >included or not is based on user-visible, new functionality, or >performance improvement. Applicable changes are included as >relnotes items even if the changes are small, I think the current granularity is good. > 2. Do you want technical details? For example, just "disk access >performance was improved by 50%" or "Feature A has been added. >This changes the old behavior because ..., and as a result, it >improves disk access performance by 50%". I want technical details. You could compromise here by trying to always have the non-technical end result in the first sentence or so, and then go on with a more technical explanation. I would echo Mark Felder and say that if in doubt, more detail is better. > 3. Is there missing information which should be in the relnotes? >Probably there are some missing items for each release, but this >question is one at some abstraction level. Link to commit log and >diff, detailed description of major incompatible changes, and so >on. I've not ever noticed any. Thanks! I'm on the SVN mailing lists so I tend to know about or be able to find changes I care about independent of the release notes. However if there is a mostly-automated way to link to specific commits in the release notes that could be valuable. > Although the other release documentations---Errata, Installation > Notes, ReadMe, and Hardware Notes---also need some improvements, > please focus on Release Notes only. And you might think quality of > English writing are not good, please leave that alone for now. I've never noticed any language problems in the release notes, and I tend to be a stickler. :) JN ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
Re: request for your comments on release documentation
On Jun 12, 2013, at 5:31 PM, Ben Morrow wrote: > Quoth h...@freebsd.org: >> >> I would like your comments on release notes for each release. >> Although I have been working on editing them for years, the workflow >> is still not optimal and sometimes delay of the preparation became an >> obstacle for release process. I would like to improve it, but before >> that I would like to know what are desired of the contents which >> people think. >> >> Release Notes is just listing the changes between the two releases. >> It includes user-visible change (bugfix and/or UI change), new >> functionality, and performance improvement. Minor changes such as >> one in kernel internal structure are omitted. I always try to keep >> these series of relnotes items are correct and reasonably >> comprehensive, but this lengthy list may be boring and >> technically-correct descriptions can be cryptic for average users. > > I find the lengthy list extremely valuable. It takes a little time to go > through it carefully, but being able to be reasonably sure nothing > important is missing makes upgrades easier, not harder. > >> So, my questions are: >> >> 1. What do you think about current granularity of the relnotes items? >>Too detailed, good, or too rough? Currently, judgment of what is >>included or not is based on user-visible, new functionality, or >>performance improvement. Applicable changes are included as >>relnotes items even if the changes are small, > > Seems pretty good to me. The only thing I might change is the order: > generally speaking, I'm most interested in the 'User-visible > incompatibilites' section, then in the userland and contrib changes, and > then the kernel changes. The security advisories section is least > useful, because it generally just lists advisories I've already seen and > know have been already fixed; it's a good thing it's there, if only to > make it clear the project takes security seriously, but I might move it > to the end. > >> 2. Do you want technical details? For example, just "disk access >>performance was improved by 50%" or "Feature A has been added. >>This changes the old behavior because ..., and as a result, it >>improves disk access performance by 50%". > > It's interesting, but IMHO only worth it if it's easy. It's not worth > holding a release up for. > >> 3. Is there missing information which should be in the relnotes? >>Probably there are some missing items for each release, but this >>question is one at some abstraction level. Link to commit log and >>diff, detailed description of major incompatible changes, and so >>on. > > The only important additional thing that might be useful would be links > to relevant mailing-list threads in addition to the SVN links. I can see > that might be quite a bit of work to compile, though, so it may not be > possible. > >> Although the other release documentations---Errata, Installation >> Notes, ReadMe, and Hardware Notes---also need some improvements, >> please focus on Release Notes only. And you might think quality of >> English writing are not good, please leave that alone for now. > > There's nothing wrong with your English. > > Ben > > __ Two points. I like the details of the release notes . More detail here is always welcomed. As a professional FreeBSD SA it helps to have detailed notes. Second, goes to item 3 noted above: a summary of pr' filed on the previous release and their current state would be a huge help as well. Say in the case of 9.0 to 9.1 it would help if I could read pr's filed about 9.0 that were fixed / addressed, etc in 9.1 . --- Mark saad | mark.s...@longcount.org ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
Re: request for your comments on release documentation
Quoth h...@freebsd.org: > > I would like your comments on release notes for each release. > Although I have been working on editing them for years, the workflow > is still not optimal and sometimes delay of the preparation became an > obstacle for release process. I would like to improve it, but before > that I would like to know what are desired of the contents which > people think. > > Release Notes is just listing the changes between the two releases. > It includes user-visible change (bugfix and/or UI change), new > functionality, and performance improvement. Minor changes such as > one in kernel internal structure are omitted. I always try to keep > these series of relnotes items are correct and reasonably > comprehensive, but this lengthy list may be boring and > technically-correct descriptions can be cryptic for average users. I find the lengthy list extremely valuable. It takes a little time to go through it carefully, but being able to be reasonably sure nothing important is missing makes upgrades easier, not harder. > So, my questions are: > > 1. What do you think about current granularity of the relnotes items? > Too detailed, good, or too rough? Currently, judgment of what is > included or not is based on user-visible, new functionality, or > performance improvement. Applicable changes are included as > relnotes items even if the changes are small, Seems pretty good to me. The only thing I might change is the order: generally speaking, I'm most interested in the 'User-visible incompatibilites' section, then in the userland and contrib changes, and then the kernel changes. The security advisories section is least useful, because it generally just lists advisories I've already seen and know have been already fixed; it's a good thing it's there, if only to make it clear the project takes security seriously, but I might move it to the end. > 2. Do you want technical details? For example, just "disk access > performance was improved by 50%" or "Feature A has been added. > This changes the old behavior because ..., and as a result, it > improves disk access performance by 50%". It's interesting, but IMHO only worth it if it's easy. It's not worth holding a release up for. > 3. Is there missing information which should be in the relnotes? > Probably there are some missing items for each release, but this > question is one at some abstraction level. Link to commit log and > diff, detailed description of major incompatible changes, and so > on. The only important additional thing that might be useful would be links to relevant mailing-list threads in addition to the SVN links. I can see that might be quite a bit of work to compile, though, so it may not be possible. > Although the other release documentations---Errata, Installation > Notes, ReadMe, and Hardware Notes---also need some improvements, > please focus on Release Notes only. And you might think quality of > English writing are not good, please leave that alone for now. There's nothing wrong with your English. Ben ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
Re: request for your comments on release documentation
On Wed, 12 Jun 2013 12:49:21 -0500, Hiroki Sato wrote: So, my questions are: 1. What do you think about current granularity of the relnotes items? Too detailed, good, or too rough? Currently, judgment of what is included or not is based on user-visible, new functionality, or performance improvement. Applicable changes are included as relnotes items even if the changes are small, As a sysadmin I live and die by the granularity of release notes. If they weren't granular I'd end up having to read the commit logs and try to parse out changes myself. Sometimes changes aren't going to be obvious if you weren't aware of discussions on the -hackers, -current, or -stable lists. 2. Do you want technical details? For example, just "disk access performance was improved by 50%" or "Feature A has been added. This changes the old behavior because ..., and as a result, it improves disk access performance by 50%". I'm sure if you're too terse like in your first example people will jump to conclusions and be angry when disk performance isn't improved 50% in every possible situation, as well as the project receiving bad press for being too deceiving. If you want to be terse perhaps "Disk access improvements" is sufficient, and use the second example if you want to be more explicit. 3. Is there missing information which should be in the relnotes? Probably there are some missing items for each release, but this question is one at some abstraction level. Link to commit log and diff, detailed description of major incompatible changes, and so on. I try to keep up with the development and changes in releases as best I can and I haven't noticed any glaring omissions over the last several releases. I think you're doing a fine job. Also, is there a reason this isn't a "living" document that can be updated as things get MFC'd to STABLE? It would help take load off your end and maybe speed up release once the freeze has happened and we begin the final grind through release candidates. ___ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "freebsd-stable-unsubscr...@freebsd.org"
request for your comments on release documentation
Hi, I would like your comments on release notes for each release. Although I have been working on editing them for years, the workflow is still not optimal and sometimes delay of the preparation became an obstacle for release process. I would like to improve it, but before that I would like to know what are desired of the contents which people think. Release Notes is just listing the changes between the two releases. It includes user-visible change (bugfix and/or UI change), new functionality, and performance improvement. Minor changes such as one in kernel internal structure are omitted. I always try to keep these series of relnotes items are correct and reasonably comprehensive, but this lengthy list may be boring and technically-correct descriptions can be cryptic for average users. So, my questions are: 1. What do you think about current granularity of the relnotes items? Too detailed, good, or too rough? Currently, judgment of what is included or not is based on user-visible, new functionality, or performance improvement. Applicable changes are included as relnotes items even if the changes are small, 2. Do you want technical details? For example, just "disk access performance was improved by 50%" or "Feature A has been added. This changes the old behavior because ..., and as a result, it improves disk access performance by 50%". 3. Is there missing information which should be in the relnotes? Probably there are some missing items for each release, but this question is one at some abstraction level. Link to commit log and diff, detailed description of major incompatible changes, and so on. Although the other release documentations---Errata, Installation Notes, ReadMe, and Hardware Notes---also need some improvements, please focus on Release Notes only. And you might think quality of English writing are not good, please leave that alone for now. -- Hiroki pgp5vPNysGiJt.pgp Description: PGP signature
