|
Size: 2681
Comment:
|
Size: 2903
Comment: +links
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma section-numbers 3 | |
| Line 3: | Line 4: |
| 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 with a minimum of surprises. Here's an attempt to distill what our rules are: | 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. |
| Line 5: | Line 6: |
| === File formats and layout: === | Here's an attempt to distill what our '''rules''' are: |
| Line 7: | Line 8: |
| * New Mercurial should always be able to read old Mercurial repositories | [[TableOfContents]] === File formats and layout === * New Mercurial should always be able to read old Mercurial [:Repository:repositories] |
| Line 9: | Line 14: |
| * Old Mercurial should break with a meaningful error message if it can't read a new Mercurial repository * New requirements are listed in the requirements file * Revlog files have a revision flag and per-revision feature flags * User-visible changes are mentioned in the release notes |
* Old Mercurial should break with a meaningful error message if it can't read a new Mercurial repository * New requirements are listed in the [:RequirementsFile:requirements file] * [:Revlog] files have a revision flag and per-revision feature flags * User-visible changes are mentioned in the [:WhatsNew:release notes] |
| Line 15: | Line 19: |
| === Commands: === | === Commands === |
| Line 19: | Line 23: |
| * 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 |
* 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 |
| Line 25: | Line 28: |
| === Config Options: === | === Config Options === |
| Line 27: | Line 30: |
| * Config options are long-lived and should not change behavior | * [:.hgrc:Config] options are long-lived and should not change behavior |
| Line 31: | Line 34: |
| === Hooks: === | === Hooks === |
| Line 33: | Line 36: |
| * The hook calling convention is intended to be extremely stable | * The [:Hook:hook] calling convention is intended to be extremely stable |
| Line 36: | Line 39: |
| === Extensions: === | === Extensions === |
| Line 38: | Line 41: |
| * 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 |
* [: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 |
| Line 42: | Line 44: |
| === Wire protocol: === | === Wire protocol === |
| Line 44: | Line 46: |
| * The 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 47: | Line 49: |
| === Web interface: === | === Web interface === |
| Line 53: | Line 55: |
| === Internal API: === | === Internal API === |
| Line 58: | Line 60: |
See also: MercurialApi ---- CategoryContributing |
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 with a minimum of surprises.
Here's an attempt to distill what our rules are:
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 [:RequirementsFile:requirements file]
- [:Revlog] files have a revision flag and per-revision feature flags
User-visible changes are mentioned in the [:WhatsNew:release notes]
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