|
Size: 2895
Comment: fix link to RequiresFile
|
← Revision 26 as of 2015-09-25 19:46:36 ⇥
Size: 4209
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma section-numbers 3 | #pragma section-numbers 2 <<Include(A:dev)>> |
| Line 4: | Line 6: |
| 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 with a minimum of surprises. | Rules for changing Mercurial behavior and output. |
| Line 6: | Line 8: |
| Here's an attempt to distill what our '''rules''' are: | <<TableOfContents>> |
| Line 8: | Line 10: |
| [[TableOfContents]] | == Introduction == |
| Line 10: | Line 12: |
| === File formats and layout === | 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. |
| Line 12: | Line 14: |
| * New Mercurial should always be able to read old Mercurial [:Repository:repositories] | == File formats and layout == * New Mercurial should always be able to read old Mercurial [[Repository|repositories]] |
| Line 15: | Line 19: |
| * 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] |
* 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]] |
| Line 19: | Line 23: |
| === Commands === | === 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 == |
| Line 22: | Line 30: |
| * Removing a feature requires a deprecation period of at least one major release | |
| Line 28: | Line 35: |
| === Config Options === | 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. |
| Line 30: | Line 37: |
| * [:.hgrc:Config] options are long-lived and should not change behavior | 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 |
| Line 34: | Line 45: |
| === Hooks === | == Hooks == |
| Line 36: | Line 47: |
| * The [:Hook:hook] calling convention is intended to be extremely stable | * The [[Hook|hook]] calling convention is intended to be extremely stable |
| Line 39: | Line 50: |
| === Extensions === | == Extensions == |
| Line 41: | Line 52: |
| * [:UsingExtensions:Extensions] that are shipped in hgext/ follow the same compatibility rules as core code | * [[UsingExtensions|Extensions]] that are shipped in ''`hgext/`'' follow the same compatibility rules as core code |
| Line 44: | Line 55: |
| === Wire protocol === | == Wire protocol == |
| Line 46: | Line 57: |
| * The [:WireProtocol:wire protocol] can check for individual features and use them if available | * The [[WireProtocol|wire protocol]] can check for individual features and use them if available |
| Line 49: | Line 60: |
| === Web interface === | == Web interface == |
| Line 51: | Line 62: |
| * Templates from old Mercurial should continue to work with new Mercurial | |
| Line 52: | Line 64: |
| * HTML output from the web interface is moderately stable, but screen-scraping it may not be reliable | * HTML output from the web interface is moderately stable, but screen-scraping it may not be reliable (raw and atom styles are more reliable) |
| Line 55: | Line 67: |
| === Internal API === | == Internal API == |
| Line 59: | Line 71: |
| * Extensions included in hgext/ and contrib/ will be updated by the Mercurial team | * Extensions included in ''`hgext/`'' and ''`contrib/`'' will be updated by the Mercurial team * CGI scripts from old Mercurial will work with new Mercurial |
| Line 61: | Line 74: |
| See also: MercurialApi | 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 |
| Line 64: | Line 86: |
| CategoryContributing | CategoryDeveloper |
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)