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.)
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
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
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.
On Sat, Nov 10, 2012 at 5:44 PM, Federico Leva (Nemo) nemowiki@gmail.com 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
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
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@lists.wikimedia.org