Compatibility Rules

Mercurial has been used in production by major software projects since a couple months after its initial release. Thus, Mercurial has always made a serious effort to be backward compatible from release to release with a minimum of surprises. Here's an attempt to distill what our rules are:

0.1. File formats and layout:

New Mercurial should always be able to read old Mercurial repositories
Old Mercurial should always be able to pull from new Mercurial servers
Old Mercurial should break with a meaningful error message if it can't
- read a new Mercurial repository
New requirements are listed in the requirements file
Revlog files have a revision flag and per-revision feature flags
User-visible changes are mentioned in the release notes

0.2. Commands:

Changes to existing command behavior is minimal
Removing a feature requires a deprecation period of at least one major release
Output formats for commands with output likely to be parsed (especially log and status) are intended to be
- stable enough to be parsable by dumb scripts and tools
Other commands may occasionally add or change output
Changes likely to affect parsers are documented in the release notes
Meaningless return values may become sensible

0.3. Hooks:

The hook calling convention is intended to be extremely stable
New hooks and environment variables may be added, but old ones will be preserved

0.4. Wire protocol:

The wire protocol can check for individual features and use them if available
The basic wire protocol is extremely stable

0.5. Web interface:

URLs from old Mercurial should continue to work with new Mercurial
HTML output from the web interface is moderately stable, but screen-scraping it may not be reliable
However, parsing of output from raw-style URLs should be stable

0.6. Internal API:

Significant improvements to internal APIs are still being made
Writers of extensions can expect a small amount of porting work between releases
Extensions included in hgext/ and contrib/ will be updated by the Mercurial team