On Wed, May 15, 2013 at 12:04 AM, Dan Mashal dan.mas...@gmail.com wrote:
On Mon, May 13, 2013 at 12:52 PM, John J. McDonough wb8...@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
--
devel mailing list
devel@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/devel
