Preparing concise, readable release notes for 1.21

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Preparing concise, readable release notes for 1.21

Mark A. Hershberger-2
In putting together the tarball for 1.20, I had some trouble with
creating an announcement for the release that captured the really
significant changes that third party users of MediaWiki should know
about.  I hope that I can work with the developers to make this
announcement for 1.21 more informative while remaining concise.

Yes, we have the RELEASE-NOTES file, but this is really too big to be
easily comprehended by the average user of MediaWiki and it is too big
for me to scan and synthesize in the limited amount of time that I have.

I'd like to find a way to come up with something like
<https://www.mediawiki.org/wiki/MediaWiki_1.18> for every release.  Or,
at least better than what we currently have at
<https://www.mediawiki.org/wiki/MediaWiki_1.20>.

At the same time, I don't want to impose an onerous burden on
developers, so I'd like to figure out how to keep the the MediaWiki_1.21
page up to date as we go along.

One idea I had was scanning the changes in RELEASE-NOTES on a, say,
weekly basis and updating the current MediaWiki_X.xx page.

Another was asking code reviewers to somehow flag commits in Gerrit as a
signal for a volunteer (like me) to add it to the current MediaWiki_X.xx
page: "Hey! this really should get more attention."

But these are just my ideas right now.  I'm open to suggestions for how
to improve the release process for MediaWiki.

(Oh, and if you know of something that the average user of MediaWiki
should really know, but that isn't yet included on
<https://www.mediawiki.org/wiki/MediaWiki_1.20>, then, please, update
the page.)

--
http://hexmode.com/

Any time you have "one overriding idea", and push your idea as a
    superior ideology, you're going to be wrong. ... The fact is,
    reality is complicated -- Linus Torvalds <http://hexm.de/mc>

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

Andre Klapper-2
On Sat, 2012-11-10 at 20:07 -0500, Mark A. Hershberger wrote:
> One idea I had was scanning the changes in RELEASE-NOTES on a, say,
> weekly basis and updating the current MediaWiki_X.xx page.
>
> Another was asking code reviewers to somehow flag commits in Gerrit as a
> signal for a volunteer (like me) to add it to the current MediaWiki_X.xx
> page: "Hey! this really should get more attention."
>
> But these are just my ideas right now.  I'm open to suggestions for how
> to improve the release process for MediaWiki.

Mozilla has a "relnotes" keyword in their Bugzilla so developers can
mark fixes worth to mention, but obviously not every commit/merge has a
corresponding ticket in the bugtracker (especially in case of
functionality enhancements).
I don't know about the acceptance by developers though (how many are
aware of it and how many actually use that keyword).

andre
--
Andre Klapper | Wikimedia Bugwrangler
http://blogs.gnome.org/aklapper/


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

Federico Leva (Nemo)
In reply to this post by Mark A. Hershberger-2
Thanks Mark for opening this discussion, it's very useful.

Indeed, by reading https://www.mediawiki.org/wiki/MediaWiki_1.20 one
would think that nobody has been done in 1.20, except perhaps some
localisation work. :p
I also agree that https://www.mediawiki.org/wiki/MediaWiki_1.18 is a
good example to follow.

On RELEASE-NOTES: it *might* be comprehensive enough (quite often things
get forgotten), but in my experience it's completely useless to
understand what are the really important things, unless one is looking
for something in particular (which is, IMHO, the point of release notes
besides big deprecation warnings and so on).
The /wmfX subpages are perhaps even less useful, as they're just list of
commits for now (crucial, but not for all users), although I see that a
section "The biggest changes" has been added (mostly empty it seems?).
https://www.mediawiki.org/wiki/MediaWiki_1.21/wmf3
Scanning a dozen sub-releases makes one lose the overview of the really
important things anyway.

I don't know if free-form tagging in gerrit will solve all our problems,
but for now I can't think of anything better than adding a short note to
https://www.mediawiki.org/wiki/MediaWiki_1.21
It doesn't need to be more than a [[gerrit:12345]] link, or a link to a
topic on gerrit, or whatever. People caring about the page will look for
more information later.
When you have that pleasing feeling "hurray my new awesome
feature/long-waited-for bugfix has been merged", adding a link to a wiki
page should be too much of a burden I think?

A simple thing that many software projects have and we seem to be
missing is an automatic list of bugs fixed in a release: we only have
target milestones. This means that:
1) your only option are release notes, which can be forgotten quite easily;
2) sometimes a bug is fixed in a branch but not in the main release and
we have no way to tag it as such.

Finally, we should perhaps also add some information on the main
extensions, especially the ones bundled in the release?

Nemo

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

Mark A. Hershberger-2
On 11/10/2012 08:44 PM, Federico Leva (Nemo) wrote:
> Finally, we should perhaps also add some information on the main
> extensions, especially the ones bundled in the release?

Ah! I forgot about these.  And since they are included now and contain a
lot of what is considered (by many) to be "core" functionality,
including their significant changes in the tarball's announcement makes
sense.

Mark.


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

Rob Lanphier-4
In reply to this post by Federico Leva (Nemo)
On Sat, Nov 10, 2012 at 5:44 PM, Federico Leva (Nemo)
<[hidden email]> wrote:
> Indeed, by reading https://www.mediawiki.org/wiki/MediaWiki_1.20 one would
> think that nobody has been done in 1.20, except perhaps some localisation
> work. :p


One thing that we might want to take note of is new extensions that
require 1.20 in order to run.  A lot of time, the work that happens in
core is in service of writing extensions (new hooks and other
architectural shuffling).  For example, here's the new hooks in 1.20:
https://www.mediawiki.org/wiki/Category:Hooks_added_in_MediaWiki_1.20.0

I'm sure all of those hooks have a corresponding extension that needs
the new hook.

Of course, maybe all new extensions would be candidates for inclusion,
regardless of whether they require 1.20.  A lot of the functionality
that end-users and site administrators really care about exists in
extensions.  Deciding which extensions are noteworthy for release
notes is perhaps a tough problem, so I could understand a desire not
to get mired in that discussion, but I suspect its the work we all do
on extensions that people look for when they're looking for the new
goodies in 1.20.

Rob

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

Federico Leva (Nemo)
Robla wrote:
 > I'm sure all of those hooks have a corresponding extension that needs
 > the new hook.

Right! (Kudos to iAlex for creating all those pages.)
However, most extension pages don't have updated lists of used hooks, so
WhatLinksHere doesn't help.
I suspect it might be easier (!) to check the MediaWiki release
requirement in the extension infobox: maybe {{Extension}} could be
changed so that it autocategorizes by required release?
Maybe if there's a central updated location where to look for such
information users will start using it and devs will think it's worth
spending a few minutes to update the docs.

A for hooks, I've seen people removing them (as well as |parameters= and
|rights= ) from extension pages because it's too tedious to update them,
they change too much and devs can already find them easily in the code.
I think they're all registered in a standard way, so a bot could be
written to update extension pages regularly; it would be very useful.

Nemo

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Preparing concise, readable release notes for 1.21

jidanni
In reply to this post by Mark A. Hershberger-2
Another problem is we people doing oh, say monthly updates from git, and
hoping to get a summary of what to be aware of. The best I can do
currently is

        git fetch origin
        git diff master..origin/master \
            RELEASE-NOTES-*|
        tee /tmp/gitdiff$$|wdiff -d -3 > /tmp/mediawikiDiff$$
        ${PAGER-less} /tmp/mediawikiDiff$$

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l