Compatibility Rules

Mercurial has been used in production by major [:ProjectsUsingMercurial: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.

Here's an attempt to distill what our rules are:

TableOfContents

1. File formats and layout

• New Mercurial should always be able to read old Mercurial [:Repository: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 [:RequiresFile:requires file]

• [:Revlog] files have a revision flag and per-revision feature flags

• User-visible changes are mentioned in the [:WhatsNew:release notes]

1.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).

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

3. Config Options

• [:.hgrc: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

4. Hooks

• The [:Hook:hook] calling convention is intended to be extremely stable

• New hooks and environment variables may be added, but old ones will be preserved

5. Extensions

• [:UsingExtensions: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

6. Wire protocol

• The [:WireProtocol:wire protocol] can check for individual features and use them if available

• The basic wire protocol is extremely stable

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

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

See also: MercurialApi

CategoryContributing