In addition to (even better than?) a breaking-changes list would be for every piece of software we distribute to have a very prominent ChangeLog (or RELEASE-NOTES) file, which is kept up to date. When you git pull and see a change to ChangeLog, that should be a clue to check out whether you need to update.php/npm install/composer update/etc.
Mediawiki core is pretty good about this, but almost too much so -- the RELEASE-NOTES gets so big it's hard to see the latest thing that broke. For most projects it's best if the very top of the ChangeLog has the most recent breaking changes. --scott On Thu, Feb 12, 2015 at 9:18 AM, Amir E. Aharoni < [email protected]> wrote: > I do have a lot of respect towards the people who work on modularization > and librarizatin and vagrant and all that, but yes - I generally agree. > There's the API mailing list, and many emails on it are about breaking > changes, but it has relatively low traffic in general, so it's OK to mix > it. Wikitech-L has very high traffic, and as Andrew says, such > announcements can get lost, if they are sent at all. So a separate > MediaWiki-breaking-changes-L list sounds quite reasonable to me. > > And I offer some simple yardsticks for defining a "breaking change": > * It's definitely a breaking change if your local site stops working after > running `git pull`. > * It's definitely a breaking change if it's in core or in an extension used > by Wikimedia, and it requires running any of the following: > ** update.php > ** composer update (not every minor new version of an external library, but > a MediaWiki feature that depends on that new version) > * It's definitely a breaking change if it's in core or in an extension used > by Wikimedia, and it requires changing Git configuration. > > Other suggestions are welcme. > > A recent example of such change is the series of changes in the way that > skins' source is managed. It broke my installation several times and I had > to figure out how to change LocalSettings myself time after time. The > result was pretty awesome, because modularization is usually a good thing, > but I don't remember that the changes were announced in a way that was > convenient, at least to me. > > > -- > Amir Elisha Aharoni · אָמִיר אֱלִישָׁע אַהֲרוֹנִי > http://aharoni.wordpress.com > “We're living in pieces, > I want to live in peace.” – T. Moore > > 2015-02-12 15:40 GMT+02:00 Andrew Garrett <[email protected]>: > > > Hey folks, > > > > I'd to modestly propose that we talk about managing/announcing breaking > > changes to core MediaWiki architecture. > > > > I want to have this chat because I spent an hour or two yesterday trying > to > > figure out why changing default configuration options for an extension in > > MyExtension.php wasn't working. Apparently, now, you also have to change > it > > in extension.json for it to work on Vagrant. > > > > I understand that this was a change that was announced on wikitech-l, > but I > > don't think that I'm the only one who thinks that reading wikitech-l > isn't > > a good use of time, compared to, say, doing my job (irony upon ironies, I > > know). If you want to change the way that things have worked for 11 > years, > > then making engineers understand what they need to do differently is your > > responsibility, not mine. > > > > So, besides huffing and puffing, I have two small proposals: > > > > 1. We should have a low-volume list/RSS feed/twitter account/something > > where we announce major breaking changes like this, that doesn't involve > > reading 20 emails per day of other stuff that doesn't affect the way I do > > my job. > > > > 2. If we make breaking changes, the change should be really obvious so > that > > I can't spend hours trying to find out what changed. > > > > For example, when we did the i18n JSON migration (everybody seems to love > > JSON these days), and I went to change/add a message, I found that the > > message file was a completely different format, and I was clued in > straight > > away to the fact that something was different. > > > > By contrast, in this case, the way I'd done things for years suddenly > > stopped working. I've heard it justified in this particular case that > this > > is just a transition period; but it's not just a transition period for > > code, it's a transition period for practices, and therefore it's the time > > when it should be the LEAST confusing for engineers who don't care about > > your refactoring, not the MOST confusing. > > > > > > — Andrew Garrett > > _______________________________________________ > > Wikitech-l mailing list > > [email protected] > > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > _______________________________________________ > Wikitech-l mailing list > [email protected] > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > -- (http://cscott.net) _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
