Patchwork [2,of,2] discovery: fix docstring of `outgoing` class

login
register
mail settings
Submitter Manuel Jacob
Date July 15, 2020, 11:56 a.m.
Message ID <b657afba62fd67912ccd.1594814178@tmp>
Download mbox | patch
Permalink /patch/46748/
State Accepted
Headers show

Comments

Manuel Jacob - July 15, 2020, 11:56 a.m.
# HG changeset patch
# User Manuel Jacob <me@manueljacob.de>
# Date 1594805934 -7200
#      Wed Jul 15 11:38:54 2020 +0200
# Node ID b657afba62fd67912ccde8c05fb872e217f444b8
# Parent  b7d3118b1fe0d41e45f630c4dd2422f56f753d81
# EXP-Topic discovery
discovery: fix docstring of `outgoing` class

Also, introduce a more correct name `ancestorsof` for what was named
`missingheads` before. For now, we just forward `ancestorsof` to `missingheads`
until all users are changed.

There were some mistakes in the old docstring / name:

* `missingheads` (new name: `ancestorsof`) contains the revs whose ancestors
  are included in the outgoing operation. It may contain non-head revs and revs
  which are already on the remote, so the name "missingheads" is wrong in two
  ways.
* `missing` contains only ancestors of `missingheads`, so not *all nodes*
  present in local but not in remote.
* `common` might not contain all common revs, e.g. not some that are not an
  ancestor of `missingheads`.

It seems like the misleading name have fostered an actual bug (issue6372),
where `outgoing.missingheads` was used assuming that it contains the heads of
the missing changesets.

Patch

diff --git a/mercurial/discovery.py b/mercurial/discovery.py
--- a/mercurial/discovery.py
+++ b/mercurial/discovery.py
@@ -75,18 +75,28 @@ 
 
 
 class outgoing(object):
-    '''Represents the set of nodes present in a local repo but not in a
-    (possibly) remote one.
+    '''Represents the result of a findcommonoutgoing() call.
 
     Members:
 
-      missing is a list of all nodes present in local but not in remote.
-      common is a list of all nodes shared between the two repos.
-      excluded is the list of missing changeset that shouldn't be sent remotely.
-      missingheads is the list of heads of missing.
+      ancestorsof is a list of the nodes whose ancestors are included in the
+      outgoing operation.
+
+      missing is a list of those ancestors of ancestorsof that are present in
+      local but not in remote.
+
+      common is a set containing revs common between the local and the remote
+      repository (at least all of those that are ancestors of ancestorsof).
+
       commonheads is the list of heads of common.
 
-    The sets are computed on demand from the heads, unless provided upfront
+      excluded is the list of missing changeset that shouldn't be sent
+      remotely.
+
+      missingheads is an alias to ancestorsof, but the name is wrong and it
+      will be removed
+
+    Some members are computed on demand from the heads, unless provided upfront
     by discovery.'''
 
     def __init__(
@@ -135,6 +145,10 @@ 
             self._computecommonmissing()
         return self._missing
 
+    @property
+    def ancestorsof(self):
+        return self.missingheads
+
 
 def findcommonoutgoing(
     repo, other, onlyheads=None, force=False, commoninc=None, portable=False