Compatibility Rules

Rules for changing Mercurial behavior and output.

This page is intended for developers.

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 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 separator on all platforms (including Windows).

3. 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

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 demands will not be patient.

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

• 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. See also

• Mercurial API

CategoryDeveloper