Note:
This page is primarily intended for developers of Mercurial.
Compatibility Rules
Rules for changing Mercurial behavior and output.
Contents
1. Introduction
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 and from platform to platform with a minimum of surprises.
2. 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 requires file
Revlog files have a revision flag and per-revision feature flags
User-visible changes are mentioned in the release notes
2.1. Path name component separator
All file system directory paths internal to Mercurial (in dirstate, changelog, manifest, in copy records, over the wire, etc.) are assumed to have a "/" path component separator on all platforms (including Windows).
3. Commands
- Changes to existing command behavior is minimal
- 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
In particular, the output of core commands like 'hg log' and 'hg status' that are prime targets for stupid parsers cannot be changed without the addition of appropriate command line arguments. Suggestions to change the default output of these commands will not be treated with patience.
Changes to error messages and ui.debug messages are usually fine as most of these messages are not intended for parsing. One important exception is 'hg log', which uses debug messages to show more detail. Adding messages at the verbose level is also usually acceptable.
4. Config options
Config options are long-lived and should not change behavior
- We may deprecate some options, giving their replacements different names
- Undocumented config options may quietly disappear if they've outlived their usefulness
5. 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
6. Extensions
Extensions that are shipped in hgext/ follow the same compatibility rules as core code
- Bear in mind that extensions are not "canonical", and their behavior may change or break core Mercurial functionality
7. Wire protocol
The wire protocol can check for individual features and use them if available
- The basic wire protocol is extremely stable
8. Web interface
- Templates from old Mercurial should continue to work with new Mercurial
- 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 (raw and atom styles are more reliable)
- However, parsing of output from raw-style URLs should be stable
9. 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
- CGI scripts from old Mercurial will work with new Mercurial
The most stable view of the API will generally be through commands.py, simply because those functions are most directly exposed to the user.
10. Python versions
Mercurial supports Python 2.6-2.7 (see Mercurial < 3.5 for 2.4 support)