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