<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, May 15, 2013 at 12:04 AM, Dan Mashal <span dir="ltr"><<a href="mailto:dan.mashal@gmail.com" target="_blank">dan.mashal@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class=""><div class="h5">On Mon, May 13, 2013 at 12:52 PM, John J. McDonough <<a href="mailto:wb8rcr@arrl.net">wb8rcr@arrl.net</a>> wrote:<br>
> We had a short discussion of this at this morning's meeting but felt a<br>
> broader discussion here was warranted.<br>
><br>
> When preparing the Release Notes, we often ask the developers for wiki<br>
> input, and generally come up dry. More recently, we look though the<br>
> repos for changes, but the upstream release notes are often very poor or<br>
> nonexistent. Every release includes literally thousands of changed<br>
> packages, and while we strive to document "significant" changes, these<br>
> poor upstream release notes leave us little clue as to what constitutes<br>
> "significant". Certainly the feature pages get us started, but they<br>
> only capture a tiny fraction of what changes in a release.<br>
><br>
> But if we think about the maintainers, chances are they begin working on<br>
> the next thing just as soon as the compose closes for the previous<br>
> release, if not sooner. Very likely they have an interest in the<br>
> packages they are maintaining, and it would not be surprising if they<br>
> viewed some features to be important.<br>
><br>
> But by the time we ask for input, odds are they have moved on and most<br>
> of the updated packages in the new release are ancient history.<br>
><br>
> However, if we were to open the beats as soon as possible, certainly<br>
> when the compose closes or even as soon as we have converted the beats<br>
> to XML, then the developers could make a note in the wiki about what is<br>
> significant, right at the time they are working on it and interested in<br>
> it.<br>
><br>
> Of course we would still need to remind the maintainers that we want<br>
> their input, and especially that it doesn't need to be beautiful prose -<br>
> all we really need is a clue as to what is important. But I think if we<br>
> can capture the input early, we have better odds of getting more<br>
> complete release notes.<br>
><br>
> Is this something we should do? Is there something different we should<br>
> be doing?<br>
><br>
> --McD<br>
<br>
</div></div>I think you should focus on "Common Bugs" and work with the IRC support SIG.<br>
<span class=""><font color="#888888"><br>
Dan<br>
</font></span><div class=""><div class="h5">--<br></div></div></blockquote><br></div><br></div><div class="gmail_extra">I think the "Common Bugs" are well handled by the QA team and effectively feature-complete. The docs writers could probably benefit from a feedback loop with the IRC folks, I like that idea. It would help improve the guides - but not the Release Notes.<br>
<br></div><div class="gmail_extra">The goal of John's idea is to track changes better by keeping up with the developers. The existing communication channel includes <a href="https://fedoraproject.org/wiki/Category:Documentation_beats?rd=Docs/Beats">https://fedoraproject.org/wiki/Category:Documentation_beats?rd=Docs/Beats</a> , which gets cleared around branch time and worked on until beta composes start. Opening the release note beats earler is an effort to change the docs process to better align with the packagers' workflow.<br>
<br>Here's the question: If we clear this wiki space *now*, at this point in the release cycle, would you use it? If the wiki isn't an effective way to point us at the changes you're currently working on for F20 and beyond, is there something better?<br>
<br></div><div class="gmail_extra">I'll cite an example that demonstrates the changelog problem John refers to, then share a little of our process, and the issue might make a little more sense:<br><br></div><div class="gmail_extra">
In writing the release notes, I noticed `pavucontrol` had been bumped to version 2.0. I'm not picking on it's maintainers - I *like* pavucontrol, and pulseaudio as a while - but I couldn't find out what had changed. /usr/share/doc/pavucontrol-*/ had no NEWS or CHANGELOG. The packaging changelog said ~"Updating to v2.0". The upstream website had an equally release announcement, and their public git repo hadn't seen a commit since March 2011. Actually getting a diff of the source and sorting out the changes would take more time than a single package might merit.<br>
<br></div><div class="gmail_extra">So, a package gets a major version bump and I'm silent about it. There might be some really interesting things in there, and I might be just as silent about well documented changes in other packages because I didn't know or think to look for them. What we do come up with gets piled into the release notes, which is used as a base for marketing materials like release announcements and talking points. These interesting changes might miss marketing attention and press interest they would otherwise have benefited from. <br>
<br>The public at large reads the Release Notes (albeit often secondhand) and accepts them as the representation of the package maintainers' work. The docs writers can create a better product with developer help, and we're asking for input on how to make that process work.<br>
<br></div><div class="gmail_extra">--Pete<br></div></div>