Mercurial > evolve
comparison docs/obs-terms.rst @ 363:5280e7ce026d stable
doc: big update of terms and summary of the concept
This is intended to be sent to the mailing list for discussion.
| author | Pierre-Yves.David@ens-lyon.org |
|---|---|
| date | Sun, 15 Jul 2012 12:49:25 +0200 |
| parents | |
| children | c2f3cdd5a2a2 |
comparison
equal
deleted
inserted
replaced
| 362:88cee22c89f1 | 363:5280e7ce026d |
|---|---|
| 1 ----------------------------------------------------------- | |
| 2 Terminology of the obsolete concept | |
| 3 ----------------------------------------------------------- | |
| 4 | |
| 5 Obsolete marker them self | |
| 6 --------------------------------- | |
| 7 | |
| 8 The mutable concept is based on the creation of **obsolete marker**. An obsolete | |
| 9 marker register a relation between the old obsoleted changeset and its newer | |
| 10 version. | |
| 11 | |
| 12 The old changesets is called **precursors**. Its newer version are called | |
| 13 *successors*. A marker always register a single *precursors* but can refer | |
| 14 to: | |
| 15 | |
| 16 - No *successors* at all if the *precursors* if just discarded. | |
| 17 - One *successor* at all if the *precursors* have been rewritten | |
| 18 - Multiple *successors* if the *precursors* have been splitted in myltiple | |
| 19 changeset. | |
| 20 | |
| 21 The **precursors** and **successors** terms can be used on changeset directy: | |
| 22 | |
| 23 :precursors: of a changeset `A` are changesets used as *precursors* by | |
| 24 obsolete marker using changeset `A` as *successors* | |
| 25 | |
| 26 :successors: of a changeset `B` are changesets used as *successors* by | |
| 27 obsolete marker using changeset `B` as *precursors* | |
| 28 | |
| 29 *Precursors* and *successors* directly related within the same marker are called | |
| 30 **direct precursors** and **direct successors** in ambiguous situation. | |
| 31 | |
| 32 The set of all *obsolete markers* create a direct acyclic graph the same way | |
| 33 standard *parent* and *children* relation do. In this graph we have: | |
| 34 | |
| 35 :any precursors: of a `A` are transitive precursors of `A`. (*direct | |
| 36 precursors* of `A` and *precursors* of *precursors*) | |
| 37 | |
| 38 :any successors: of a `A` are transitive successors of `A`. (*direct | |
| 39 successors* of `A` and *precursors* of *precursors*) | |
| 40 | |
| 41 Obsolete markers may revert to changesets that are not known locally. *Direct | |
| 42 precursors* of a changeset may be unknown locally. This is why we usually focus | |
| 43 on the **first known precursors** of changeset | |
| 44 | |
| 45 (The same apply for successors) | |
| 46 | |
| 47 Item in *Any successors* which are not *obsolete* are called **newest | |
| 48 successors** | |
| 49 | |
| 50 .. note:: I'm not very happy with this naming scheme and I'm looking for a | |
| 51 better distinction between direct-successors, any-successors. | |
| 52 | |
| 53 Possible changesets "type" | |
| 54 --------------------------------- | |
| 55 | |
| 56 The following table describe name and behavior of changesets affected by | |
| 57 obsolete marker. Left column describe generic category and right column are | |
| 58 about sub-category. | |
| 59 | |
| 60 | |
| 61 +---------------------+--------------------------+-----------------------------+ | |
| 62 | **mutable** | **obsolete** | **extinct** | | |
| 63 | | | | | |
| 64 | Changeset in either | Obsolete changesets are | Extinct changesets are | | |
| 65 | *draft* or *secret* | mutable changeset used | obsolete one with obsolete | | |
| 66 | phases. | as a precursors. | only descendants. | | |
| 67 | | | | | |
| 68 | | A changeset is used as | They can be safely: | | |
| 69 | | a precursors when at | | | |
| 70 | | least one obsolete | - hidden in the UI, | | |
| 71 | | refer to it in the | - silently excluded from pp | | |
| 72 | | precursors field. | pull and push,t operation | | |
| 73 | | | - ignored by most operation | | |
| 74 | | | - garbage collected. | | |
| 75 | | | | | |
| 76 | | +-----------------------------+ | |
| 77 | | | | | |
| 78 | | | **suspended** | | |
| 79 | | | | | |
| 80 | | | Suspended changesets are | | |
| 81 | | | obsolete one with at least | | |
| 82 | | | one non-obsolete descendant | | |
| 83 | | | | | |
| 84 | | | Thoses descendants prevent | | |
| 85 | | | properties of extincts | | |
| 86 | | | changesets to apply. But | | |
| 87 | | | they will refuse to be | | |
| 88 | | | pushed without --force. | | |
| 89 | | | | | |
| 90 | +--------------------------+-----------------------------+ | |
| 91 | | | | | |
| 92 | | **troublesome** | **unstable** | | |
| 93 | | | | | |
| 94 | | Troublesome commit have | Unstable changesets are | | |
| 95 | | unresolved issue caused | changesets with obsolete | | |
| 96 | | by obsolete relations. | ancestors. | | |
| 97 | | | | | |
| 98 | | Possible issues are | They must be rebased on a | | |
| 99 | | listed in the next | better base to solve the | | |
| 100 | | column. It is possible | situation. | | |
| 101 | | for troublesome | | | |
| 102 | | changeset to combine | (possible alternative name: | | |
| 103 | | multiple issue at once. | precarious) | | |
| 104 | | (eg: conflicting and | | | |
| 105 | | unstable) +-----------------------------+ | |
| 106 | | | | | |
| 107 | | (possible alternative | **latecomer** | | |
| 108 | | name: unsettled, | | | |
| 109 | | troubled) | Latecomer changesets are | | |
| 110 | | | changesets that try to | | |
| 111 | | | be successors of public | | |
| 112 | | | changesets. | | |
| 113 | | | | | |
| 114 | | | Public changeset can't | | |
| 115 | | | be obsolete. Latecomer | | |
| 116 | | | changeset need to be | | |
| 117 | | | rewritten as an overlay | | |
| 118 | | | to this public changeset. | | |
| 119 | | | | | |
| 120 | | | (possible alternative names | | |
| 121 | | | mislead, naive, unaware, | | |
| 122 | | | mindless, disenchanting) | | |
| 123 | | | | | |
| 124 | | +-----------------------------+ | |
| 125 | | | **conflicting** | | |
| 126 | | | | | |
| 127 | | | Conflicting changesets | | |
| 128 | | | happen when multiple | | |
| 129 | | | changesets are successors | | |
| 130 | | | of the same obsolete | | |
| 131 | | | changeset. | | |
| 132 | | | | | |
| 133 | | | Conflicting changesets are | | |
| 134 | | | resolve through a three | | |
| 135 | | | ways merging between the | | |
| 136 | | | two conflicting changesets, | | |
| 137 | | | using the last "obsolete- | | |
| 138 | | | -common-ancestor" as the | | |
| 139 | | | base. | | |
| 140 | | | | | |
| 141 | | | (Changeset splitting is | | |
| 142 | | | properly not detected as a | | |
| 143 | | | conflict) | | |
| 144 | | | | | |
| 145 | +--------------------------+-----------------------------+ | |
| 146 | | | | |
| 147 | | Mutable changesets which are neither *obsolete* or | | |
| 148 | | *troublesome* are *"ok"*. | | |
| 149 | | | | |
| 150 | | Do we really need a name for it ? *"ok"* is a pretty | | |
| 151 | | crappy name :-/ other possibilities are: | | |
| 152 | | | | |
| 153 | | - stable (confusing with stable branch) | | |
| 154 | | - sane | | |
| 155 | | - healthy | | |
| 156 | | | | |
| 157 +---------------------+--------------------------------------------------------+ | |
| 158 | | | |
| 159 | **immutable** | | |
| 160 | | | |
| 161 | Changesets in the *public* phases. | | |
| 162 | | | |
| 163 | Rewriting operation refuse to work on immutable changeset. | | |
| 164 | | | |
| 165 | Obsolete markers that refer an immutable changeset as precursors have | | |
| 166 | no effect on the precussors changeset (but may have effect on the | | |
| 167 | successors) | | |
| 168 | | | |
| 169 | When a mutable changeset becomes immutable its is just *immutable* and loose | | |
| 170 | any property of it's former state. | | |
| 171 | | | |
| 172 | By phase property, once a changeset becomes a public immutable changeset, | | |
| 173 | you can expect it to remain as such forever. | | |
| 174 | | | |
| 175 +------------------------------------------------------------------------------+ | |
| 176 | |
| 177 .. note:: I'm not very happy with the naming of: | |
| 178 | |
| 179 - "ok" changeset | |
| 180 - latecomer | |
| 181 - troublesome | |
| 182 | |
| 183 Any better idea are welcome. | |
| 184 | |
| 185 | |
| 186 Command and operation name | |
| 187 --------------------------------- | |
| 188 | |
| 189 | |
| 190 Existing terms | |
| 191 `````````````` | |
| 192 | |
| 193 Mercurial already use the following terms: | |
| 194 | |
| 195 :amend: rewrite a changeset | |
| 196 :graft: copy a changeset | |
| 197 :rebase: move a changeset | |
| 198 | |
| 199 | |
| 200 Uncommit | |
| 201 ````````````` | |
| 202 | |
| 203 remove files from a commit (and leave them as dirty in the working directory) | |
| 204 | |
| 205 The evolve extension have an `uncommit` command that aims to replace most | |
| 206 `rollback` usage. | |
| 207 | |
| 208 Fold | |
| 209 `````````` | |
| 210 | |
| 211 Collapse multiple changeset into one | |
| 212 | |
| 213 The evolve extensions *will* have a `fold` commands | |
| 214 | |
| 215 Prune | |
| 216 `````````` | |
| 217 | |
| 218 Make a changeset obsolete without successors. | |
| 219 | |
| 220 This an important operation as it should replace strip in 95% of the case. | |
| 221 | |
| 222 alternative name: | |
| 223 | |
| 224 - kill: nice name for effect when you forget the "hg" in front on "hg kill". | |
| 225 - obsolete: too vague, long and generic. | |
| 226 | |
| 227 Stabilize | |
| 228 ``````````````` | |
| 229 | |
| 230 Automatically resolve troublesome changesets | |
| 231 (unstable, latecomer and conflicting) | |
| 232 | |
| 233 This is an important name as hg pull/pussh will suggest it the same way it | |
| 234 suggest merging when you add heads. | |
| 235 | |
| 236 I do not like stabilize much. | |
| 237 | |
| 238 alternative name: | |
| 239 | |
| 240 - solve (too generic ?) | |
| 241 - evolve (too vague) | |
| 242 | |
| 243 | |
| 244 | |
| 245 | |
| 246 | |
| 247 .. note:: I'm not very happy with the naming of: | |
| 248 | |
| 249 - "ok" changeset | |
| 250 - latecomer | |
| 251 - troublesome | |
| 252 | |
| 253 Any better idea are welcome. |