Maintainer input on release notes

[Pete Travis]

On Wed, May 15, 2013 at 12:04 AM, Dan Mashal <dan.mashal at gmail.com> wrote:

> On Mon, May 13, 2013 at 12:52 PM, John J. McDonough <wb8rcr at arrl.net>
> wrote:
> > We had a short discussion of this at this morning's meeting but felt a
> > broader discussion here was warranted.
> >
> > When preparing the Release Notes, we often ask the developers for wiki
> > input, and generally come up dry. More recently, we look though the
> > repos for changes, but the upstream release notes are often very poor or
> > nonexistent. Every release includes literally thousands of changed
> > packages, and while we strive to document "significant" changes, these
> > poor upstream release notes leave us little clue as to what constitutes
> > "significant".  Certainly the feature pages get us started, but they
> > only capture a tiny fraction of what changes in a release.
> >
> > But if we think about the maintainers, chances are they begin working on
> > the next thing just as soon as the compose closes for the previous
> > release, if not sooner.  Very likely they have an interest in the
> > packages they are maintaining, and it would not be surprising if they
> > viewed some features to be important.
> >
> > But by the time we ask for input, odds are they have moved on and most
> > of the updated packages in the new release are ancient history.
> >
> > However, if we were to open the beats as soon as possible, certainly
> > when the compose closes or even as soon as we have converted the beats
> > to XML, then the developers could make a note in the wiki about what is
> > significant, right at the time they are working on it and interested in
> > it.
> >
> > Of course we would still need to remind the maintainers that we want
> > their input, and especially that it doesn't need to be beautiful prose -
> > all we really need is a clue as to what is important.  But I think if we
> > can capture the input early, we have better odds of getting more
> > complete release notes.
> >
> > Is this something we should do?  Is there something different we should
> > be doing?
> >
> > --McD
>
> I think you should focus on "Common Bugs" and work with the IRC support
> SIG.
>
> Dan
> --
>


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.

The goal of John's idea is to track changes better by keeping up with the
developers.  The existing communication channel includes
https://fedoraproject.org/wiki/Category:Documentation_beats?rd=Docs/Beats ,
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.

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?

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:

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.

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.

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.

--Pete
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/devel/attachments/20130515/49b61621/attachment.html>