This is an add-on to the interesting article How to break an API which shows how several projects handle backward compatibility (Eclipse, R and Node.js). This article presents the position of the XWiki open source project.

The XWiki Ecosystem: Extensible wiki and framework, over 800 extensions since 2004

The XWiki project started in 2004, it's now 12 years old. It can be seen as a professional wiki but it's much more. It's actually a platform for developing collaborative web apps and thus it provides lots of API. The whole of XWiki can be accessed through API and the default wiki provided is just an example of what you can achieve with the API (similar to Eclipse JDT - the IDE - which is just an example of what can be done with Eclipse APIs).

 XWiki extensions developed 10 years ago can still be installed in the newest versions of XWiki and will mostly work (some small UI aspects may be off a bit but the API calls will still work).

Community Values in XWiki

The consequence of XWiki being a platform is that XWiki users develop applications in their wikis, using APIs. XWiki can be seen as a language and once a language is mature, it should not break APIs.

A core value of the XWiki community is backward compatibility. 

Thus XWiki has developed a strong set of practices and tools to ensure that APIs do not get broken.

The philosophy can be summed as:

• Full backward compatibility to reduce costs for users scripting in wiki pages
• Backward compatibility to reduce costs for maintainers to the maximum

Change Practices and Costs in XWiki

Speed of Development

The XWiki open source project has developed several strategies to balance the cost of preserving backward compatibility with the ability to innovate at the same time:

• @Unstable annotation to signify to developers when a new API is introduced and can be subject to changes. Changes during one full cycle is allowed (which means up to 2 years in the unstable state). This is to acknowledge the fact that creating an API right on the first try is an almost impossible feat. In addition, the XWiki project has an automated build-time enforcer to break the build if an @Unstable annotations remains in the code but its time has elapsed (using the @since version). Example of usage:
  /**
   * Provides instance-specific scripting APIs.
   * [...]
   * @since 8.3RC1
   */
  @Unstable
  public class InstanceScriptService implements ScriptService
  {
     ...
  }
• XWiki uses a @deprecated strategy but once the core code has been modified to not use the deprecated API anymore, the API is moved to a legacy build module. This is done using AspectJ. XWiki releases the legacy modules and they're included by default in the distribution. However when developer build XWiki every day, they build without it (CI builds with it) and they don't see those APIs. Thus no code uses deprecated APIs once they've been moved out!

However the XWiki project takes substantial time and effort to ensure backward compatibility all the time. 3 examples:

•  When the rendering engine was redone in 2007 the existing engine of the time was left in and instead a notion of configurable syntax was introduced and based on the page syntax the old rendering engine was used or the new one was used. A bridge support for the old syntax was even implemented in the new rendering engine and after several years (8 years!), the old syntax and old rendering were moved as an optional extension, not bundled by default in the distribution. They can still be installed very easily though!
• When support for Nested Pages was introduced in 2015, it was a huge refactoring that touched almost all aspects of the code base. Yet a lot of actions were taken to preserve backward compatibility (at the expense of innovation in a few cases, for example for the link reference notation which became more complex than it should be). A Migrator application was even written to help users migrate.
• When database schema changes are done, the XWiki project always provide automatic migrators that are executed under the hood when users upgrade their XWiki instances.