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
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 agarrett@wikimedia.org:
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:
- 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.
- 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 < amir.aharoni@mail.huji.ac.il> 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 agarrett@wikimedia.org:
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:
- 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.
- 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
There is the https://lists.wikimedia.org/mailman/listinfo/wikitech-announce email list which perhaps could be used for emailing the weekly tech newsletters and major changes.
Pine On Feb 12, 2015 7:25 AM, "C. Scott Ananian" cananian@wikimedia.org wrote:
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 < amir.aharoni@mail.huji.ac.il> 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 agarrett@wikimedia.org:
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:
- 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.
- 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
-- (http://cscott.net) _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Pine W wrote:
There is the https://lists.wikimedia.org/mailman/listinfo/wikitech-announce email list which perhaps could be used for emailing the weekly tech newsletters and major changes.
There's also the mediawiki-announce list. While new mailing lists are cheap enough to create, I don't think a new list is warranted here. I think the better approach, as mentioned, is to focus on improving documentation and error reporting.
MZMcBride
Hi,
On Thu, Feb 12, 2015 at 7:24 AM, C. Scott Ananian cananian@wikimedia.org wrote:
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.
We're currently having a discussion about how to better surface changes with noteworthy user impact, and we're considering using a Phabricator tag / project for this purpose. The same system could be adopted for changes with noteworthy developer impact: https://phabricator.wikimedia.org/T88468#1037411
I don't think we need to announce every change that requires running update.php-- that's pretty common, and (most importantly, imho) the error messages you get when that happens make it pretty obvious what you need to do.
But +1 for standardizing where breaking changes are announced. I hit the issue yesterday with profiling. It's been updated, the change wasn't announced on wikitech-l, and the wiki page about it is wrong. So I'd also like to also suggest that if you make a breaking change: * please make sure mediawiki.org is updated to reflect the change * please fail in a way that tells the user what went wrong
I know I'm guilty of making breaking changes that don't comply with this, so I'm preaching to myself too. But I think that would generally help.
On Thu, Feb 12, 2015 at 6:18 AM, Amir E. Aharoni amir.aharoni@mail.huji.ac.il 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 agarrett@wikimedia.org:
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:
- 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.
- 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Thu, Feb 12, 2015 at 6:08 PM, Chris Steipp csteipp@wikimedia.org wrote:
- please fail in a way that tells the user what went wrong
This is my most important point.
I don't mind changing the code I write to conform to new (improved!) ways of doing things. I think those who are writing configuration objects and extension managers and libraryizing and serviceizing and generally improving our code and eliminating technical debt are doing the (figurative) Lord's Work.
Just, make it so that if I do things the "Old Way", I find out in an obvious way that there is a New Way, and you don't waste hours of my time trying to find out what changed.
As much as possible, I think we should rely on useful error messages and obvious signs in the code that something has changed, not required reading. I don't want to have to do homework to do my job – if people move my cheese then I'd like them to at least leave a note telling me where it's been moved to.
The point of removing technical debt is that it improves engineer productivity – if you make engineers spend hours reading mailing lists and tracing bugs then those benefits dissipate.
— Andrew Garrett
Regarding "everyone loves JSON these days":
I truly, deeply, hate it.
On Thu, Feb 12, 2015 at 2:40 PM, Andrew Garrett agarrett@wikimedia.org wrote:
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:
- 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.
- 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
wikitech-l@lists.wikimedia.org