annotate docs/unstability.rst @ 228:5a17c0d41a00

proof-read documentation and docstrings
author Nicolas Chauvat <nicolas.chauvat@logilab.fr>
date Wed, 09 May 2012 14:24:56 +0200
parents abe52cf492ee
children f589d054329a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
1 -----------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
2 The Unstability Principle
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
3 -----------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
4
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
5
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
6
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
7 An intrinsic contradiction
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
8 -----------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
9
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
10
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
11 DVCS bring two new major concepts to the Version Control Scene:
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
12
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
13 * Organisation of the history with robust DAG,
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
14 * Mutation of history.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
15
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
16
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
17 However, the two concepts opposes them self:
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
18
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
19 To achieve a robust history, three key elements are gathered in *changeset*:
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
20
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
21 * Full snapshot of the versioned content,
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
22 * Reference to the previous full snapshot used to build the new one,
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
23 * A description of the change who lead from the old content to the new old.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
24
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
25 All three elements are used generate a *unique* hash that identify the changeset
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
26 (with various other metadata). This identification is a key part of DVCS design.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
27
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
28 ::
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
29
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
30 Schema base, A, B and B'
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
31
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
32 The old changeset is usually discarded
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
33 t in DVCS history.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
34
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
35
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
36 ::
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
37
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
38 Schema base, A and A' and B.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
39
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
40 Rewriting a changeset with children does not changes children parent! And
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
41 because children of the rewritten changeset still **depends** on the older
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
42 "dead" version of the changeset with can not get ride of this dead version.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
43
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
44 This is a very useful property because Changing B parent means changing B
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
45 content too. This require the creation of **another** changeset.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
46
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
47 I'll qualify those children as **unstable** because they are based one a dead
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
48 changeset and prevent people to get ride of it.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
49
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
50 This instability is an **unavoidable consequence** of the strict dependency of
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
51 changese. History Rewriting history alway need to take it in account and
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
52 provide a way to rewrite the descendant on the new changeset to avoid
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
53 coexistence of the old and new version of a rewritten changeset..
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
54
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
55
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
56 Everybody is working around the issue
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
57 ------------------------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
58
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
59 I'm not claiming that rewriting history is impossible. People are
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
60
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
61
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
62
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
63 Rewriting all at once
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
64 ``````````````````````````
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
65
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
66
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
67
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
68 stable situation to stable situation
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
69
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
70 Distributed means that you do not control what happen outside your repository:
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
71
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
72
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
73 * phase.
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
74 * overwrite.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
75
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
76
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
77 Boiler Plate
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
78
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
79
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
80 Loose the DAG robustness
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
81 ````````````````````````````
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
82
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
83 The other approach is
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
84
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
85 mq -- quilt
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
86
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
87 Conflict too much conflict
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
88
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
89 Linear
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
90
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
91
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
92 Deny a lot of option
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
93 ````````````````````````````
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
94
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
95
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
96
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
97 [] rewrite
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
98
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
99 [] exchange
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
100
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
101 [] collaborate
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
102
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
103
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
104 Facing The Danger Once And For All
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
105 ------------------------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
106 The more effort you put to avoid instability, the more option you deny. And even
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
107 most restrictive work flow can't garantee that instability will never show up!
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
108
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
109 It is time to provide a full featured solution to deal with instability and to
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
110 stop working around the issue! This is why I developing a new feature for
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
111 mercurial called "Obsolete marker".
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
112
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
113
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
114 * Any changeset is we want to get ride of is **explicitly** marked as "obsolete"
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
115 by history rewritting operation..
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
116
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
117 * Relations between old and new version of changesets are tracked by Obsolete
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
118 markers.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
119
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
120 By explicitly marking the obsolete part of the history, we will be able to
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
121 easily detect appearance of unstability. By Storing a meta-history of changeset
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
122 evolution we are able to easily resolve instability and edition conflict.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
123
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
124
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
125
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
126
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
127 No instability is still a bad situation.
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
128 No instability is still a bad situation that should be avoided.