This page is primarily intended for developers of Mercurial.

Compatibility Rules

Rules for changing Mercurial behavior and output.

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

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

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

5. Hooks

6. Extensions

7. Wire protocol

8. Web interface

9. Internal API

The most stable view of the API will generally be through, 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)

11. See also


CompatibilityRules (last edited 2015-09-25 19:46:36 by Pierre-YvesDavid)