How to announce backward incompatible changes in OSS project?

Question

Sometimes you need to introduce backward incompatibile changes, when the improvements far outweighs the downsides. It is possible to easily switch to old behavior, but the user must be aware of such changes.

Therefore the question is: how to announce future backward incompatible changes to FLOSS (open source) project, so that users can prepare for them, and either change their use, or configure program to use old behavior.

Because it is OSS project, it is packaged by various distributions independently, and might be upgraded automatically without user intervention. And then backward incompatible change might mess somebodys workflow (third party scripts for example).

Avenues currently considered (and used):

• project mailing list
• project homepage
• release notes (first warning, then announcement)
• maintainer's blog

Edit 1: This (backward incompatible) change would happen in some major release.

All changes are about either adding safeguards (refusing commands which can thoroughly confuse newbie users), or changing defaults to more sane values.

Edit 2: In the transition period the default configuration (which is meant to be changed to default refuse/deny) is changed to warn, with description how to turn of a warning, which also would protect against backward incompatibile change in default behavior.

But if it is automated system that might not help...

---

The project in question is Git, distributed version control system;
see Giving early warning to users at gitster's journal (Junio C Hamano blog)

Answer 1

• Change the major of the version number
• Announce it through all avenues at your disposal
• Add prominent announcement in readme
• Add code that converts between the old and new if DB or other changes are required
• Add code that detects the use of depreciated methods, data storage, etc and alerts the user before performing destructive changes
• Ask relevant FAQ type questions on major Q/A websites so when people have queries the answer is immediate and obvious using a simple search

But the major version number is the primary target - people expect 1.x to 2.x transitions to cause issues, and are more careful when upgrading.

Answer 2

Just my $0.02. Modern development environments (specifically, .NET) provide means of reporting to the developer that certain APIs are declared obsolete/deprecated and will be removed in future versions. Microsoft C/C++ compiler has #pragma deprecated.

If none of this is supported in your environment, rely on versioning to provide compat feedback.

Answer 3

I could go for RSS (if exists), Twitter (if exists), mailing list (mail at least 3 times as the update is closing in), homepage (make it very contrasting, so it's easy to see) and blog, of course. release notes are scarcely read, so take it as the last point of information.

(I posted this as first answer, but didn't show up)

Answer 4

All the above plus.

If you have a change where:

The exact syntax of a non destructive command would change to be a destructive command

I see no option but making the change instead more disruptive to render the old command entirely invalid so that if a user upgrades and attempts (or quite possibly a script attempts) the old style command it terminates with a descriptive error message on stderr. Using stderr for warning messages on commands with subtle (or not so subtle) changes which are non destructive is also a good idea. The definition of destructive is somewhat more complex on a source repository

Using stderr warnings for simple deprecation methods is often good but some people will complain it breaks their (badly written) scripts. In these cases a silent deprecation release (all non invasive forms of deprecation) followed by a verbal (stderr warnings) release followed perhaps (see below) with a non functional but present release followed then by total removal. This last non functional release will be heavily dependant on the project in question as it could be more trouble than it's worth, especially to those users who are well behaved and keep up to date on deprecated functionality.

Since the specific change you reference is the removal of the built ins this should be fine I probably wouldn't have done one release with the built-ins in a non functional mode but I don't know the project well enough to say for sure.

Note for code rather than script level changes it is possible in many modern languages to leave in method stubs with attributes/annotations which will entirely hide them from intellisense as well as refuse to compile against them. This makes their presence (with a simple exception if used) a much nicer way of finding out you can't use them than a runtime MissingMethodException or whatever.

Answer 5

You've got good answers about getting the word out. But migrating my own mindset is the biggest issue for me, particularly when the deprecated functions are in my muscle memory. Unlearning is harder than learning.

Getting warnings of coming incompatibilites when I'm actually using the commands that are going to change is particularly helpful, especially with changes in defaults. Something like:

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.