hg: update top-level script to use modern import conventions

simplemerge: update to conform with modern import conventions

contrib: inform import checker that __builtin__ is a thing

contrib: allow importing "symbols" from mercurial

hgperf: update to conform with import style checks

contrib: update hg-ssh to conform with import style checks

contrib: have import-checker work mostly with native strings for mod names Module names are a bit awkward to deal with portably otherwise.

bundlerepo: move bundle2 part handling out to a function This moves the bundle2 part handling for bundlerepo out to a separate function so extensions can participate in bundlerepo setup when using bundle2 bundles. Differential Revision: https://phab.mercurial-scm.org/D290

bundle2: seek part back during iteration Previously, iterparts would yield the part to users, then consume the part. This changed the part after the user was given it and left it at the end, both of which seem unexpected. Let's seek back to the beginning after we've consumed it. I tried not seeking to the end at all, but that seems important for the overall bundle2 consumption. This is used in a future patch to let us move the bundlerepo bundle2-changegroup-part to be handled entirely within the for loop, instead of having to do a seek back to 0 after the entire loop finishes. Differential Revision: https://phab.mercurial-scm.org/D289

bundlerepo: move temp bundle creation to a separate function A future patch will refactor certain parts of bundlerepo initiatlization such that we need to create temp bundles from another function. Let's move this to another function to support that. Differential Revision: https://phab.mercurial-scm.org/D288

exchange: don't attempt phase exchange if phase-heads was in bundle The Mercurial core server doesn't yet include phase-heads parts in the bundle, but our Google-internal server wants to do that. Unfortunately, the usual exchange still happens even if phase-heads part is included (including the short-circuited one for old/publishing servers). That means that even if our server (again, the Google-internal one, but also future Mercurial core servers) includes a phase-heads part to indicate that some heads should be drafts, that would still get overwritten by the phase updating that happens after. So let's fix that by marking the phase step done if we receive at least one phase-heads part in the bundle. Differential Revision: https://phab.mercurial-scm.org/D440

pushvars: do not mangle repo state Setting `repo._shellvars` works but is not a clean way to pass the pushvars information from the push command to the exchange operation. Therefore change it to actually pass `pushvars` as a push operation argument instead. This makes third party extension like remotenames easier to support pushvars cleanly. The key value parsing and verification code has been moved to a lower level so it's harder to be bypassed and easier to be used in remotenames which could replace `push` command entirely. Differential Revision: https://phab.mercurial-scm.org/D423

record: fix revert -i for lines without newline (issue5651) This is a regression caused by 66117dae87f9. Code prior to 66117dae87f9 seems to miss the "\ No newline at end of file" line. Differential Revision: https://phab.mercurial-scm.org/D528

morestatus: check whether the conflict message is None before printing There are cases like bisect when the conflict message can be None. So we make sure that we don't print None in that case. Thanks to Martin for catching this. Differential Revision: https://phab.mercurial-scm.org/D461

bundle2: fixed usage of an attribute that was removed in py3k Differential Revision: https://phab.mercurial-scm.org/D482

releasenotes: add check flag for use of admonitions and its validity While using releasenotes extension, we will be using admonitions in commit messages. The check (-c) flag will look for an admonition within the message. If it exists, it will verify if it is stated under default or custom admonition. The check fails if the admonition is not present in any of them. It also suggests similar admonitions in case the admonition is invalid. Differential Revision: https://phab.mercurial-scm.org/D368

copies: fix misaligned lines

copies: fix typo in comment "will not be limited" was meant to be "will not be visited". I missed this when writing the original graft-through-rename patch series.

python3: whitelist test-imports-checker.t, which now passes

contrib: make import checker always think in terms of bytes The doctests now do some regrettable things, but they'll always work since we're dealing with ASCII module names etc.

contrib: work around some modules not existing on Py3 in import checker

tests: stop using old except syntax in test-bundle2-format

tests: update test-archive to always use hashlib We don't need the fallback to the old modules anymore.

md5sum: assume hashlib exists now that we're 2.7 only

undumprevlog: update to valid Python 3 syntax I didn't do anything to ensure correctness here, just enough to avoid tracebacks in the import checker, which uses the native ast module to try and parse all our Python files.

tests: fixed a bytes/unicode confusion in the test runner Differential Revision: https://phab.mercurial-scm.org/D483

run-tests: remove unused pygments token type Differential Revision: https://phab.mercurial-scm.org/D478

run-tests: also highlight .py test files in summary messages With the .t files highlighted, it's very easy to not even notice failed .py tests. Differential Revision: https://phab.mercurial-scm.org/D471

test-revset: make it work with chg chg currently triggers `reposetup` as a side effect of `hg serve` command. Therefore change the test to not output during `reposetup` to be compatible with chg. Differential Revision: https://phab.mercurial-scm.org/D455

copies: use intersectmatchers() in non-merge p1 optimization This enables the optimization introduced by d4247c306d82 for non-rebase cases. Before, the match couldn't be narrowed if it was e.g. alwaysmatcher. The logic is copied from bd56bea5ecf8.

run-tests: pre instantiate pygments objects Pre instantiate pygments objects to minimize overhead (cf. 20436925e080)

merge with stable

rebase: only change self.state when collapsing in _finishrebase When the code executes to _finishrebase, self.state should be populated with correct destinations and do not need to be written to a node. The code was introduced by 8dc45c9059, which seems to avoid setting state values to None but it didn't provide more details. Differential Revision: https://phab.mercurial-scm.org/D346

rebase: choose merge base without unwanted revisions Previously, when there are 2 merge base candidates, we choose p1 blindly, which may make the merge result to have "unwanted content". This patch makes rebase smarter - choose a merge base that does not have "unwanted revs" if possible. Since we don't really have a good solution when there are "unwanted revs", abort in that case. Differential Revision: https://phab.mercurial-scm.org/D340

templatekw: choose {latesttag} by len(changes), not date (issue5659) As Augie reported in the bug, the current heuristic of choosing the best tag of a merge commit by taking the one with newest tag (in terms of tagging date) currently fails in the Mercurial repo itself. Copying the example from Yuya: $ hg glog -T '{node|short} {latesttag}+{latesttagdistance}\n' \ -r '4.2.3: & (merge() + parents(merge()) + tag())' o 02a745c20121 4.2.3+5 |\ | o 86aca74a063b 4.2.3+4 | |\ | | o e6d8ee3c9ec3 4.3-rc+109 | | | | | ~ o | a3ce07e2dde5 4.3.1+2 : | o | 3fee7f7d2da0 4.3.1+0 |/ o 98e990bb7330 4.2.3+3 |\ | ~ o 506d7e48fbe6 4.2.3+2 : o 943c91326b23 4.2.3+0 | ~ It seems to me like the best choice is the tag with the smallest number of changes since it (across all paths, not the longest single path). So that's what this patch does, even though it's costly. Best-of-5 timings for Yuya's command above shows a slowdown from 1.293s to 1.610s. We can optimize it later. Differential Revision: https://phab.mercurial-scm.org/D447

tests: use graph log in {latesttag} tests The tests are much easier to read if one does not have to re-read the setup part all the time to understand the graph shape. Differential Revision: https://phab.mercurial-scm.org/D446

demandimport: disable if chg is being used In chg's case, making modules lazily loaded could actually slow down things since chg pre-imports them. Therefore disable demandimport if chg is being used. This is not done by setting `HGDEMANDIMPORT` chg client-side because that has side-effects on child processes (hooks, etc). Differential Revision: https://phab.mercurial-scm.org/D351

demandimport: move HGDEMANDIMPORT test to __init__.py The logic is now shared between demandimport{2,3}. Differential Revision: https://phab.mercurial-scm.org/D445

log: add a "graphwidth" template variable Wrapping text in templates for 'hg log --graph' can't be done very well, because the template doesn't know how wide the graph drawing is. The edge drawing function needs to know the number of lines in the template output, so we need to also determine how wide that drawing would be before we call the edgefn or evaluate the template. This patch makes edgefn compute the graph width and pass it into the template so that we can do something like this: COLUMNS=10 hg log --graph --template "{fill(desc, termwidth - graphwidth)}" @ a a a a | a a a a | a a a a o a a a |\ a a a | | a a a | | a a a Using extensions to do this would be relatively complicated due to a lack of hooks in this area of the code. In the future it may make sense to have a more generic "textwidth" that tells you how many columns you can expect to fill without causing the terminal to wrap your output. I'm not sure there are other situations to motivate this yet, or if it is entirely feasible. Differential Revision: https://phab.mercurial-scm.org/D360

obsmarker: fix precnode deprecation The deprecation message for marker.precnode was wrong. Fix the typo. Differential Revision: https://phab.mercurial-scm.org/D413

obsmarker: precnode was renamed into prednode Update all calls to formatter.write first arguments to remove references to precnode and use prednode consistently everywhere. Differential Revision: https://phab.mercurial-scm.org/D414

revset: mark evolution-related revsets as experimental Differential Revision: https://phab.mercurial-scm.org/D416

push: fix docsstring Seems the code block misses `::`. This patch makes sure `[push]` and `pushvars.server = true` are in two lines. Differential Revision: https://phab.mercurial-scm.org/D411

py3: select input or raw_input by pycompat This seems slightly cleaner.

py3: make encoding.strio() an identity function on Python 2 It's the convention the other encoding.str*() functions follow. To make things simple, this also drops kwargs from the strio() constructor.

templatekw: specify plural form of instability Follows up 40739aef97f7.

templatekw: rename termwidth() per convention

rebase: optimize "source" calculation in adjustdest The "source" variable is calculated inside a loop but it does not depend on loop variables. Therefore move it outside the loop. Differential Revision: https://phab.mercurial-scm.org/D345

rebase: remove "state >= revtodo" condition Now the minimal value of state is revtodo, that condition is always true, therefore removed. Differential Revision: https://phab.mercurial-scm.org/D344

rebase: remove self.destancestors The state is no longer used after calculating "self.external", therefore removed. Differential Revision: https://phab.mercurial-scm.org/D343

rebase: remove rebaseset from _checkobsrebase The parameter is not used. Therefore removed. Differential Revision: https://phab.mercurial-scm.org/D85

rebase: remove revignored and nullmerge states They are no longer necessary to make rebase behavior correct. Therefore remove them to make the code cleaner and easier to reason about. Differential Revision: https://phab.mercurial-scm.org/D26

rebase: remove messages for nullmerge and revignored (BC) These states will be removed to make the code cleaner and more robust. Remove their messages first to make review easier. Differential Revision: https://phab.mercurial-scm.org/D25

rebase: remove revprecursor and revpruned states (BC) Those states are no longer necessary for rebase to function properly. Remove them to make the code cleaner. Marked as BC because in a corner case where working parent is obsoleted, and is skipped for rebase, we no longer move working parent after rebase completes. That is better since if working parent is obsoleted, it should be the user moving working parent back there (after a rebase) explicitly, in that case, we shouldn't move working parent again. Differential Revision: https://phab.mercurial-scm.org/D24

rebase: move obsoleted not rebased messages earlier (BC) A later patch will clean up those states. This patch moves the messages earlier. Marked as BC since the order of message has changed. Differential Revision: https://phab.mercurial-scm.org/D23

rebase: extract ctx description logic to a function The function will be used in a later patch. Differential Revision: https://phab.mercurial-scm.org/D22

python3: whitelist another *13* tests that now pass Differential Revision: https://phab.mercurial-scm.org/D302

py3: introduce a wrapper for __builtins__.{raw_,}input() In order to make this work, we have to wrap the io streams in a TextIOWrapper so that __builtins__.input() can do unicode IO on Python 3. We can't just restore the original (unicode) sys.std* because we might be running a cmdserver, and if we blindly restore sys.* to the original values then we end up breaking the cmdserver. Sadly, TextIOWrapper tries to close the underlying stream during its __del__, so we have to make a sublcass to prevent that. If you see errors like: TypeError: a bytes-like object is required, not 'str' On an input() or print() call on Python 3, the substitution of sys.std* is probably the root cause. A previous version of this change tried to put the bytesinput() method in pycompat - it turns out we need to do some encoding handling, so we have to be in a higher layer that's allowed to use mercurial.encoding.encoding. As a result, this is in util for now, with the TextIOWrapper subclass hiding in encoding.py. I'm not sure of a better place for the time being. Differential Revision: https://phab.mercurial-scm.org/D299

python3: whitelist four more passing tests Differential Revision: https://phab.mercurial-scm.org/D298

extensions: don't give AttributeError bytes message on Python 3 Differential Revision: https://phab.mercurial-scm.org/D353

extensions: if on py3 and propname is a bytestr, convert to sysstr Property names are unicodes on Python 3. Differential Revision: https://phab.mercurial-scm.org/D296

pushvars: add a coreconfigitem for push.pushvars.server Differential Revision: https://phab.mercurial-scm.org/D359

phabricator: add phabupdate command to update status in batch Changing status (accept, etc) on the webpage is not very convenient - currently there is no way to accept (or abandon etc.) a stack using a single click or command. This patch adds a `phabupdate` command that could be used to change status in batch. It also supports `--comment` which will write a comment on the last revision, which is similar to what we do using emails. Differential Revision: https://phab.mercurial-scm.org/D127

phabricator: add status to revision query language This patch adds status words (ex. `abandoned`, `accepted`, `needsreview`, `needsrevision`, `closed`) to the revision query language so people can select revision in a more flexible way. Test Plan: Try something like `phabread ':2 & accepted'`, `phabread ':105 - closed` and make sure they have desired outputs. Differential Revision: https://phab.mercurial-scm.org/D126

phabricator: add a small language to query Differential Revisions Previously, `phabread` can only be used to read a single patch, or a single stack of patches. In the future, we want to have more complex queries like filtering with status (open, accepted, closed, etc), or maybe more complex like filtering by reviewers etc. The command line flag approach won't scale with that. Besides, we might want to have other commands to update Differential Revision status in batch, like accepting a stack using a single command. Therefore, this patch adds a small language. It has basic set operations: `&`, `+`, `-` and an ancestor operator to support `--stack`. Test Plan: Try querying this Phabricator instance: hg phabread 1+2 # 1, 2 hg phabread D2+D1 # 2, 1 hg phabread ':118-115+:2-1' # 114, 116, 117, 118, 2 hg phabread '((:118-(D115+117)))&:117' # 114, 116 hg phabread ':2&:117' --debug # differential.query is called only once Make sure the output is expected and prefetch works. Differential Revision: https://phab.mercurial-scm.org/D125

phabricator: change "readpatch" to be more flexible Previously, `readpatch` and `querydrev` take a same `params` and `stack` parameters. This patch changes `readpatch` so it takes the output of `querydrev`, not the input of `querydrev`. This makes the code more flexible and cleaner. Differential Revision: https://phab.mercurial-scm.org/D124

filemerge: extract `_picklabels` as a helper function This shortens `simplemerge()` and is a bit cleaner, IMO. Differential Revision: https://phab.mercurial-scm.org/D376

simplemerge: write merge result to the localctx, if passed Differential Revision: https://phab.mercurial-scm.org/D375

simplemerge: use contexts to read file data from, if passed Differential Revision: https://phab.mercurial-scm.org/D374

filemerge: pass contexts to simplemerge Otherwise, this should be a no-op. Differential Revision: https://phab.mercurial-scm.org/D373

simplemerge: add optional context parameters to simplemerge Rename the existing parameters for clarity. These will, in subsequent patches, allow callers to redirect reads (of the three sides of the merge) and writes (of the result) to the given contexts, instead of using the filesystem. While in most cases, the writes will go to a workingfilectx, this opens the door for it to be a memfilectx in the case of an in-memory merge. Repo will be necessary in a subsequent comit. Differential Revision: https://phab.mercurial-scm.org/D372

simplemerge: extract verifytext as a helper function This will be used in a subsequent commit. Differential Revision: https://phab.mercurial-scm.org/D371

commit: use context manager with dirstateguard When I wrote 5ac845ca059a (commit: don't let failed commit with --addremove update dirstate (issue5645), 2017-07-31), Durham's 609606d21765 (rebase: use one dirstateguard for when using rebase.singletransaction, 2017-07-20) had not yet landed, so I had to write it in the old-fashioned way. Now that Durham's patch is in, we can simplify by using a context manager. Differential Revision: https://phab.mercurial-scm.org/D406

commit: move dirstateguard creation out of try-block This is just a simple refactoring to make the next patch simpler. If the dirstateguard constructor raises an exception, the finally-block won't do anything anyway, so this is functionally equivalent (and there is no except-block). Differential Revision: https://phab.mercurial-scm.org/D405

copies: add more details to the documentation of mergecopies() This documentation is very helpful for any developer to understand what copytracing is and what the function does. Since this is the main function of doing copytracing, I have also included bits about copytracing in it. This additions are picked from a doc by Stash@Fb. So thanks to him. Differential Revision: https://phab.mercurial-scm.org/D409

httppeer: add support for httppostargs when we're sending a file This is probably only used in the 'unbundle' command, but the code ended up being cleaner to make it generic and treat *all* httppostargs with a non-args request body as though they were file-like in nature. It also means we get test coverage more or less for free. A previous version of this change didn't use io.BytesIO, and it was a lot more complicated. This also fixes a server-side bug, so anyone using httppostargs should update all of their servers to this revision or later *before* this gets to their clients, otherwise servers will hang trying to over-read the POST body. Differential Revision: https://phab.mercurial-scm.org/D231

i18n: get translation entries for description of each compression engines Now, hggettext can be applied safely on util.py, of which i18nfunctions contains appropriate objects related to each compression types.

i18n: ignore docstring for modules under mercurial Docstring of modules is needed only for "hg help -e EXTNAME". This is a preparation for applying hggettext on util.py, which has module docstring, but it isn't needed for translation.

i18n: use saved object to get actual function information if available To list up available compression types instead of ".. bundlecompressionmarker" in "hg help bundlespec" output, proxy object "docobject" is used, because: - current online help system requires that __doc__ of registered object (maybe, function) is already well formatted in reST syntax - bundletype() method of compressionengine classes is used to list up available compression types, but - __doc__ of bundletype() object (= "instancemethod") is read-only On the other hand, hggettext requires original function object, in order to get document location in source code. Therefore, description of each compression types isn't yet translatable. Even if translatable, translators should make much effort to determine location of original texts in source code. To get actual function information, this patch makes hggettext use function object saved as "_origfunc", if it is available. This patch also changes bundlecompressiontopics() side, in order to explain how these changes work easily. This patch is a part of preparations for making description of each compression types translatable.

i18n: ignore doctest part to avoid warning at "make update-pot" hggettext assumes that backslashes in docstring are always doubled in original source code, in order to find the location of original docstring out certainly. This assumption almost always works as expected. But doctest easily breaks it, because many of backslashes in doctests aren't doubled. This mismatching causes "unknown offset in ..." warning at "make update-pot". To avoid such warning, this patch ignores doctest part of docstring before finding the location of original docstring out. BTW, at this patch, only person() in templatefilters.py has doctest part, which causes "unknown offset ..." warning. Therefore, just making backslashes in that doctest doubled can avoid such warning, too. But forcing doctest writers to double backslashes in doctest isn't reasonable, IMHO.

largefiles: fix help text to avoid warning at "make update-pot" This change helps hggettext to find out help text in original source, because it assumes that backslash ('\') is doubled in docstring.

i18n: make hggettext use original docstring to compute offset Before this patch, hggettext uses __doc__ of each functions to compute offset of document text. But __doc__ of many functions is already modified by decorators in registrar (e.g. @templatekeyword adds ":NAME: " prefix to it), and hggettext can not find it out in original source. This causes many "unknown offset in ..." warning at "make update-pot", and leaving them might cause overlooking serious problems. This patch makes hggettext use original docstring, which decorators in registrar save into _origdoc, to compute offset. Even after this patch, there are still a few "unknown offset in ..." warning at "make update-pot" for specific reasons. These will be fixed later one by one.

run-tests: also color the summary messages (skipped, failed...)

crecord: fixes the formatting of the select status in the status line The status line in the crecord has the "space" status field which has variable length depending on the length of the status label in the language of choice. In English, the status labels are "space: deselect" and "space:select". The "deselect" label is 2 glyphs longer. This makes the terminal output jump around if the terminal width is just right so that the shorter label makes the status line 1 line long, and the longer label makes it 2 lines long. This patch formats the selected status into a fixed-width field. The field width is the maximum of the lengths of the two possible labels, to account for differing translations and label lengths. This should make the label behavior uniform across localizations. There does not seem to be a test for crecord, so I verified the change manually with a local build of 'hg'.

cext: move PyInt macros to charencode.c properly Python3 build was broken at e9996bd7203f.

py3: change encoding.localstr to a subclass of bytes, not str

bundle2: relax the condition to update transaction.hookargs This is just a micro optimization. If hookargs is empty, nothing should be necessary.

bundle2: raise ProgrammingError for invalid call of addhookargs() It should be hard error. Also fixed the error message as s/hooks/hookargs/.

merge: removed sorting in casefolding detection, for a slight performance win It was not required for the correctness of the algorithm. Differential Revision: https://phab.mercurial-scm.org/D30

tests: verify that peer instances only expose interface members Our abstract interfaces are more useful if we guarantee that implementations conform to certain rules. Namely, we want to ensure that objects implementing interfaces don't expose new public attributes that aren't part of the interface. That way, as long as consumers don't access "internal" attributes (those beginning with "_") then (in theory) objects implementing interfaces can be swapped out and everything will "just work." We add a test that enforces our "no public attributes not part of the abstract interface" rule. We /could/ implement "interface compliance detection" at run-time. However, that is littered with problems. The obvious solutions are custom __new__ and __init__ methods. These rely on derived types actually calling the parent's implementation, which is no sure bet. Furthermore, __new__ and __init__ will likely be called before instance-specific attributes are assigned. In other words, they won't detect public attributes set on self.__dict__. This means public attribute detection won't be robust. We could work around lack of robust self.__dict__ public attribute detection by having our interfaces implement a custom __getattribute__, __getattr__, and/or __setattr__. However, this incurs an undesirable run-time penalty. And, subclasses could override our custom method, bypassing the check. The most robust solution is a non-runtime test. So that's what this commit implements. We have a generic function for validating that an object only has public attributes defined by abstract classes. Then, we instantiate some peers and verify a newly constructed object plays by the rules. Differential Revision: https://phab.mercurial-scm.org/D339

wireproto: use new peer interface The wirepeer class provides concrete implementations of peer interface methods for calling wire protocol commands. It makes sense for this class to inherit from the peer abstract base class. So we change that. Since httppeer and sshpeer have already been converted to the new interface, peerrepository is no longer adding any value. So it has been removed. httppeer and sshpeer have been updated to reflect the loss of peerrepository and the inheritance of the abstract base class in wirepeer. The code changes in wirepeer are reordering of methods to group by interface. Some Python code in tests was updated to reflect changed APIs. .. api:: peer.peerrepository has been removed. Use repository.peer abstract base class to represent a peer repository. Differential Revision: https://phab.mercurial-scm.org/D338

httppeer: use peer interface This is similar to what we did to sshpeer. Quirks and all. Differential Revision: https://phab.mercurial-scm.org/D337

sshpeer: use peer interface We need the same @property conversion of ui like we did for localpeer. We renamed _capabilities() to capabilities() to satisfy the new naming requirement. However, since we're inheriting from wireproto.wirepeer which inherits from peer.peerrepository and provides its own code accessing _capabilities(), we need to keep the old alias around. This wonkiness will disappear once wirepeer is cleaned up in subsequent commits. We also implement methods for basepeer that are identical to the defaults in peer.peerrepository in preparation for the removal of peerrepository. Differential Revision: https://phab.mercurial-scm.org/D336

localrepo: use peer interfaces We now have a formal abstract base class for peers. Let's transition the peer classes in localrepo to it. As part of the transition, we reorder methods so they are grouped by interface and match the order they are defined in the interface. We also had to change self.ui from an instance attribute to a property to satisfy the @abstractproperty requirement. As part of this change, we uncover the first "bug" as part of enforcing interfaces: stream_out() wasn't implemented on localpeer! This isn't technically a bug since the repo isn't advertising the stream capability, so clients shouldn't be attempting to call it. But I don't think there's a good reason why this is the case. We implement a dummy method to satisfy the interface requriements. We can make localpeer instances streamable as a future enhancement. # no-check-commit Differential Revision: https://phab.mercurial-scm.org/D335

repository: implement generic capability methods on peer class These methods are part of the peer interface, are generic, and can be implemented in terms of other members of the peer interface. So we implement them on the peer base class as a convenience. The implementation is essentially copied from peer.py. The code in peer.py will eventually be deleted. Differential Revision: https://phab.mercurial-scm.org/D334

repository: formalize wire protocol interface There are a well-defined set of commands constituting the wire protocol. Interaction with these and methods for calling them in batches are exposed via methods on peer instances. Let's formalize support for these features in abstract classes. The command parts come from the existing wireproto.wirepeer class. The batch methods come from peer.peerrepository. Ample documentation has been added as part of defining the interfaces. # no-check-commit Differential Revision: https://phab.mercurial-scm.org/D333