#pragma section-numbers 2 <> = Compatibility Rules = Rules for changing Mercurial behavior and output. <> == Introduction == 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. == 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]] === 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). == 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. == 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 == 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 == 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 == Wire protocol == * The [[WireProtocol|wire protocol]] can check for individual features and use them if available * The basic wire protocol is extremely stable == 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 == 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. == Python versions == Mercurial supports Python 2.6-2.7 (see Mercurial < 3.5 for 2.4 support) == See also == * [[MercurialApi|Mercurial API]] * FeatureLevels ---- CategoryDeveloper