docs/instability.rst
author Pierre-Yves David <pierre-yves.david@fb.com>
Tue, 11 Nov 2014 11:26:57 +0000
branchstable
changeset 1155 3ad45ed74313
parent 655 dd5765ae91c3
permissions -rw-r--r--
merge back with compat branch
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
519
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 492
diff changeset
     1
.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>
9825c7da5b54 ensure all file have a copyright notice
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 492
diff changeset
     2
..                Logilab SA        <contact@logilab.fr>
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
     3
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     4
-----------------------------------
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
     5
The instability Principle
221
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
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
An intrinsic contradiction
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    11
-----------------------------------
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    12
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    13
XXX starts by talking about getting ride of changeset.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    14
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    15
DVCSes bring two new major concepts to the version control scene:
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    16
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    17
    * History is organized as a robust DAG,
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    18
    * History can be rewritten.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    19
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    20
However, the two concepts are in contradiction:
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    21
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    22
To achieve a robust history, three key elements are gathered in *changesets*:
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    23
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    24
    * Full snapshot of the versioned content,
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    25
    * Reference to the previous full snapshot used to build the new one,
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    26
    * A description of the change which leads from the old content to the new content.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    27
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    28
All three elements are used to compute a *unique* hash that identifies the changeset
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    29
(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
    30
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    31
This is a very useful property because changing B's parent means
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    32
changing B's content too. This requires the creation of **another**
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    33
changeset, which is semantically good.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    34
574
4f5562c92630 more schema
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 519
diff changeset
    35
.. figure:: ./figures/edit-is-rewrite-step2.svg
221
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
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    38
To avoid duplication, the older changeset is usually discarded from accessible
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    39
history. I'm calling them *obsolete* changesets.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    40
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    41
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    42
But rewriting a changeset with children does not change the
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    43
children's parents! And because children of the rewritten changeset
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    44
still **depend** on the older "dead" version of the changeset, we
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    45
cannot get rid of this dead version.
221
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
::
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    48
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    49
  Schema base,  A and A' and B.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    50
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    51
I'm calling these children **unstable** because they are based on a
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    52
dead changeset and prevent people from getting rid of it.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    53
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    54
This instability is an **unavoidable consequence** of the strict dependency of
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    55
changesets.  Rewriting history always needs to take it into account and
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    56
provide a way to rewrite the descendants of the new changeset to avoid
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    57
coexistence of the old and new versions of a rewritten changeset.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    58
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    59
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    60
Everybody is working around the issue
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
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    63
I'm not claiming that rewriting history is impossible. People have been successfully
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    64
doing it for years. However they all need to work around *instability*. Several
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    65
workaround strategies exist.
221
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
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    68
Rewriting all at once
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    69
``````````````````````````
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    70
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    71
The simplest way to avoid instability is to ensure rewriting
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    72
operations always end in a stable situation. This is achieved by
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    73
rewriting all affected changesets at the same time.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    74
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    75
Rewriting all descendants at the same time when rewriting a changeset.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    76
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    77
::
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    78
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    79
  Schema!
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    80
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    81
Several Mercurial commands apply it: rebase, collapse, histedit.
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    82
Mercurial also refuses to amend changesets with descendants. The git
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    83
branch design enforces this approach in git too.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    84
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    85
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    86
However, DVCS are **distributed**. This means that you do not control what
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    87
happens outside your repository. Once a changeset has been exchanged *outside*,
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    88
there is no way to be sure it does not have descendants somewhere else.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    89
Therefore **if you rewrite changeset that exists elsewhere, you can't eradicate
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    90
the risk of instability.**
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    91
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
    92
Do not rewrite exchanged changesets
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
    93
```````````````````````````````````
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    94
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    95
To work around the issue above, Mercurial introduced phases, which
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    96
prevent you from rewriting shared changesets and ensure others can't
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    97
pull certain changesets from you. But this is a very frustrating
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    98
limitation that prevents you to efficiently sharing, reviewing and
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
    99
collaborating on mutable changesets.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   100
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   101
In the Git world, they use another approach to prevent instability. By
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   102
convention only a single developer works on a changeset contained in
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   103
a named branch. But once again this is a huge blocker for
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   104
collaborating. Moreover clueless people **will** mess up social
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   105
convention soon or later.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   106
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   107
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   108
Lose the DAG robustness
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   109
````````````````````````````
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   110
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   111
The other approach in Mercurial is to keep the mutable part of the
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   112
history outside the DVCS constraint. This is the MQ approach of
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   113
sticking a quilt queue over Mercurial.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   114
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   115
This allow much more flexible workflow but two major feature are lost in the
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   116
process:
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   117
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   118
:graceful merge: MQ uses plain patch to store changeset contents, which has
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   119
                 problems in changing context. Applying your queue
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   120
                 becomes very painful when context changes.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   121
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   122
:easy branching: A quilt queue is by definition a linear queue, increasing risk
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   123
                 of conflict.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   124
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   125
It is possible to collaborate over versioned MQ! But you are going to
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   126
have a lot of trouble.
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   127
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   128
Ignore conflicts
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   129
```````````````````````````````````
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   130
 
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   131
Another ignored issue is a conflicting rewrite of the same changeset.
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   132
If a changeset is rewritten two times we have two newer versions,
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   133
and duplicated history is complicated to merge.
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   134
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   135
Mercurial work around by
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   136
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   137
The "One set of mutable changset == One developer" mantra is also a way to work
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   138
around conflicting rewriting of changeset. If two different people are able to
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   139
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   140
The git branch model allows overwriting changeset version by another
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   141
one, but it does not care about divergent version. It is the equivalent
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   142
of "common ftp" source management for changesets.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   143
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   144
Facing The Danger Once And For All
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   145
------------------------------------------------
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   146
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   147
Above we saw that the more effort you put to avoid instability, the more options
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   148
you deny. And even the most restrictive workflow can't guarantee that instability
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   149
will never show up!
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   150
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   151
Obsolete marker can handle the job
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   152
```````````````````````````````````
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   153
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   154
It is time to provide a full-featured solution to deal with
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   155
instability and to stop working around the issue! This is why I
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   156
am developing a new feature for Mercurial called "Obsolete markers".
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   157
Obsolete markers have two key properties:
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   158
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   159
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   160
* Any "old" changeset we want to get rid of is **explicitly** marked
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   161
  as "obsolete" by history rewriting operations.
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   162
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   163
  By explicitly marking the obsolete part of the history, we will be able to
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   164
  easily detect instability situation.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   165
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   166
* Relations between old and new version of changesets are tracked by obsolete
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   167
  markers.
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   168
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   169
  By storing a meta-history of changeset evolution we are able to easily resolve
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   170
  instability and edit conflicts [#]_ .
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   171
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   172
.. [#] Edit conflicts is another major obstable to collaboration. See the
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   173
       section dedicated to obsolete marker for details.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   174
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   175
Improved robustness == improved simplicity
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   176
````````````````````````````````````````````````
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   177
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   178
This proposal should **first** be seen as a safety measure.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   179
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   180
It allows detecting instability as soon as possible.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   181
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   182
::
240
ab9ee2eba21e [doc] fix unstable code block
Pierre-Yves.David@ens-lyon.org
parents: 231
diff changeset
   183
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   184
    $ hg pull
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   185
    added 3 changeset
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   186
    +2 unstable changeset
492
7ecd41520dae rename `stabilize` to `evolve`
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 365
diff changeset
   187
    (do you want "hg evolve" ?)
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   188
    working directory parent is obsolete!
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   189
    $ hg push
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   190
    outgoing unstable changesets
492
7ecd41520dae rename `stabilize` to `evolve`
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 365
diff changeset
   191
    (use "hg evolve" or force the push)
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   192
655
dd5765ae91c3 doc: fix grammar, spelling, punctuation
Greg Ward <greg@gerg.ca>
parents: 574
diff changeset
   193
And it should not not encourage people to create instability.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   194
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   195
::
240
ab9ee2eba21e [doc] fix unstable code block
Pierre-Yves.David@ens-lyon.org
parents: 231
diff changeset
   196
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   197
    $ hg up 42
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   198
    $ hg commit --amend
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   199
    changeset have descendant.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   200
    $ hg commit --amend -f
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   201
    +5 unstable changeset
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   202
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   203
    $ hg rebase -D --rev 40::44
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   204
    rebasing already obsolete changeset 42:AAA will conflict with newer version 48:BBB
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   205
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   206
While allowing powerful feature
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   207
````````````````````````````````````````````````
221
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   208
d43b72724b84 doc: unstability principle
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   209
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   210
* Help to automatically solve instability.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   211
365
9f6a77ec66cb evolve: switch the official name for "kill" to prune
Pierre-Yves.David@ens-lyon.org
parents: 357
diff changeset
   212
* "prune" changeset remotely.
231
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   213
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   214
* track resulting changeset when submitting patch//pull request.
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   215
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   216
* Focus on what you do:
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   217
f589d054329a restore unstability content
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 228
diff changeset
   218
  I do not like the "all at once" model of history rewriting. I'm comfortable
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   219
  with instability and obsolete marker offer all the tool to safely create and
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 243
diff changeset
   220
  handle instability locally.
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   221
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   222