Maintainer input on release notes

John J. McDonough wb8rcr at arrl.net
Mon May 13 19:52:50 UTC 2013


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





More information about the docs mailing list