docs/index.rst
author Pulkit Goyal <7895pulkit@gmail.com>
Fri, 23 Mar 2018 17:20:20 +0530
changeset 3621 db3ec5f79ab9
parent 3471 2a337fcedd5e
child 5226 38d225efcea9
permissions -rw-r--r--
tests: add one more test case about handling of phase-divergence by evolve This patch adds a test case when phasedivergence is caused by rebase command and there is parent change involved. As the tests show, we are not handling things correctly here. Upcoming patches will fix that. Fixing things in later patches showed there was a wrong case in one another test which will be fixed by later patches, so let's add description on why that test is wrong in this patch.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     1
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     2
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     3
==================================
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     4
Changeset Evolution with Mercurial
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
     5
==================================
709
60582b861a00 minor help changes
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 667
diff changeset
     6
2879
3fd8acc06780 doc-front-page: mention that "Changeset Evolution" is a specific concept
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2878
diff changeset
     7
`evolve`_ is a Mercurial extension for faster and safer mutable history. It
2884
5a836fa589a4 doc-front-page: link to the changeset evolution section in the document
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2883
diff changeset
     8
implements the `changeset evolution`_ concept for `Mercurial`_.
2873
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
     9
2876
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    10
* It offers a safe and simple way to refine changesets locally and propagate
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    11
  those changes to other repositories.
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    12
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    13
* It can automatically detect and handle the complex issues that can arise from
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    14
  exchanging draft changesets.
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    15
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    16
* It even makes it possible for multiple developers to safely rewrite the same
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    17
  parts of history in a distributed way.
2876
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    18
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    19
* It fully respects the Phases concept so users will only be able to rewrite
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    20
  parts of the history that are safe to change. Phases have been part of
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    21
  Mercurial since early 2012.
2876
c47c988b239b doc-front-page: add a feature summary at the beginning of the page
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2875
diff changeset
    22
2873
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
    23
.. _`evolve`: https://www.mercurial-scm.org/wiki/EvolveExtension
2879
3fd8acc06780 doc-front-page: mention that "Changeset Evolution" is a specific concept
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2878
diff changeset
    24
.. _`Mercurial`: https://www.mercurial-scm.org/
2873
2c4171a53475 doc-front-page: move introduction before the table of content
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2872
diff changeset
    25
2874
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    26
Installation and setup
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    27
----------------------
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    28
2875
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    29
We recommend you subscribe to the `evolve-testers`_ mailing list to stay up
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    30
to date with the latest news and announcement.
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    31
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    32
.. _`evolve-testers`: https://www.mercurial-scm.org/mailman/listinfo/evolve-testers
483152bab9b9 doc-front-page: mention the mailing list in the documentation
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2874
diff changeset
    33
2874
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    34
Using pip::
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    35
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    36
    pip install --user hg-evolve
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    37
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    38
Then add in your `hgrc` config::
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    39
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    40
   [extensions]
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    41
   evolve=
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    42
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    43
You can easily edit the `hgrc` of a repository using `hg config --local`.
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    44
Alternatively, you can edit your user configuration with `hg config --edit`.
2874
2b84eee4c040 doc-front-page: move installation instruction earliero
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2873
diff changeset
    45
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    46
Table of Contents
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    47
-----------------
2878
641cdc2e4bfb doc-front-page: include the index in the TOC
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2877
diff changeset
    48
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    49
.. toctree::
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    50
   :maxdepth: 2
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    51
2878
641cdc2e4bfb doc-front-page: include the index in the TOC
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2877
diff changeset
    52
   index
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    53
   user-guide
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    54
   sharing
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    55
   concepts
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    56
   from-mq
2962
3f466d348047 doc: add documentation for evolve commands
Philippe Pepiot <phil@philpep.org>
parents: 2894
diff changeset
    57
   commands
2894
31aa9d097d29 doc: record all the missings and strange bit we know
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2887
diff changeset
    58
   known-doc-issues
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
    59
2884
5a836fa589a4 doc-front-page: link to the changeset evolution section in the document
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2883
diff changeset
    60
.. _`changeset evolution`:
5a836fa589a4 doc-front-page: link to the changeset evolution section in the document
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2883
diff changeset
    61
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    62
What is Changeset Evolution?
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    63
----------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    64
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    65
With core Mercurial, changesets are permanent and immutable. You can
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    66
commit new changesets to modify your source code, but you cannot
2871
c6289ec369cb doc: be less dramatic about changeset immutability
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2870
diff changeset
    67
modify or remove old changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    68
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    69
For years, Mercurial has included various commands that allow
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    70
history modification: ``rebase``, ``histedit``, ``commit --amend`` and so forth.
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    71
However, there's a catch: until now, Mercurial's various mechanisms for
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    72
modifying history have been *unsafe*, in that changesets were
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    73
destroyed (“stripped”) rather than simply hidden and still easy to recover.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    74
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    75
``evolve`` makes things better by changing the behaviour of most existing
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    76
history modification commands so they use a safer mechanism (*changeset
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    77
obsolescence*, covered below) rather than the older, less safe *strip*
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    78
operation.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    79
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    80
``evolve`` is built on infrastructure in core Mercurial:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
    81
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    82
  * *Phases* (starting in Mercurial 2.1) allow you to distinguish
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
    83
    mutable and immutable changesets.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
    84
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    85
  * *Changeset obsolescence* (starting in Mercurial 2.3) is how
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    86
    Mercurial knows how history has been modified, specifically when
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    87
    one changeset replaces another. In the obsolescence model, a
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    88
    changeset is neither removed nor modified, but is instead marked
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    89
    *obsolete* and typically replaced by a *successor*. Obsolete
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
    90
    changesets usually become *hidden* as well. Obsolescence is a
2881
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
    91
    disabled feature in Mercurial until you start using ``evolve``.
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    92
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    93
Some of the things you can do with ``evolve`` are:
163
92b073d13f2d more doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 161
diff changeset
    94
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    95
  * Fix a mistake immediately: “Oops! I just committed a changeset
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
    96
    with a syntax error—I'll fix that and amend the changeset so no
2881
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
    97
    one sees my mistake.” (While this is possible using default
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
    98
    features of core Mercurial, changeset evolution makes it safer.)
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
    99
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   100
  * Fix a mistake a little bit later: “Oops! I broke the tests three
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   101
    commits back, but only noticed it now—I'll just update back to the
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   102
    bad changeset, fix my mistake, amend the changeset, and evolve
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   103
    history to update the affected changesets.”
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   104
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   105
  * Remove unwanted changes: “I hacked in some debug output two
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   106
    commits back; everything is working now, so I'll just prune that
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   107
    unwanted changeset and evolve history before pushing.”
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   108
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   109
  * Share mutable history with yourself: say you do most of your
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   110
    programming work locally, but need to test on a big remote server
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   111
    somewhere before you know everything is good. You can use
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   112
    ``evolve`` to share mutable history between two computers, pushing
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   113
    finely polished changesets to a public repository only after
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   114
    testing on the test server.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
   115
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   116
  * Share mutable history for code review: you don't want to publish
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   117
    unreviewed changesets, but you can't block every commit waiting
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   118
    for code review. The solution is to share mutable history with
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   119
    your reviewer, amending each changeset until it passes review.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
   120
2881
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
   121
  * Explore and audit the rewrite history of a changeset. Since Mercurial is
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   122
    tracking the edits you make to a changeset, you can look at the history of
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   123
    these edits. This is similar to Mercurial tracking the history of file
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   124
    edits, but at the changeset level.
2881
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
   125
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   126
Why the `evolve` extension?
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   127
---------------------------
2882
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   128
2884
5a836fa589a4 doc-front-page: link to the changeset evolution section in the document
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2883
diff changeset
   129
Mercurial core already has some support for `changeset evolution`_ so why have a
2882
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   130
dedicated extension?
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   131
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   132
The long-term plan for ``evolve`` is to add it to core Mercurial. However,
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   133
having the extension helps us experiment with various user experience
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   134
approaches and technical prototypes. Having a dedicated extension helps current
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   135
users deploy the latest changes quickly and provides developers with low latency
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   136
feedback.
2882
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   137
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   138
Whenever we are happy with a experimental direction in the extension, the
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   139
relevant code can go upstream into Core Mercurial.
2882
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
   140
2883
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   141
Development status
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   142
------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
   143
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   144
While well underway, the full implementation of the `changeset evolution`_
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   145
concept is still a work in progress. Core Mercurial already supports many of the
2883
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   146
associated features, but for now they are still disabled by default. The current
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   147
implementation has been usable for multiple years already, and some parts of it
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   148
are used in production by multiple projects and companies (including the
2883
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   149
Mercurial project itself, Facebook, Google, etc…).
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   150
2883
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   151
However, there are still some areas were the current implementation has gaps.
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   152
This means some use cases or performance issues are not handled as well as they
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   153
currently are without evolution. Mercurial has been around for a long time and
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   154
is strongly committed to backward compatibility. Therefore turning evolution on
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   155
by default today could regress the experience of some of our current users. The
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   156
features will only be enabled by default at the point where users who do not use
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   157
or care about the new features added by evolution won't be negatively impacted
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   158
by the new default.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
   159
3471
2a337fcedd5e doc: add link to roadmap
Boris Feld <boris.feld@octobus.net>
parents: 2962
diff changeset
   160
You can find the `evolution roadmap in the wiki`_.
2a337fcedd5e doc: add link to roadmap
Boris Feld <boris.feld@octobus.net>
parents: 2962
diff changeset
   161
2883
a23045b61e6d doc-front-page: use a clearer statement about the experimental status
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2882
diff changeset
   162
.. # .. _`this query`: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=NEED_EXAMPLE
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   163
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   164
Resources
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
   165
---------
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
   166
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   167
  * For a practical guide to using ``evolve`` in a single repository,
978
8328337d23b2 docs: add new user guide
Greg Ward <greg@gerg.ca>
parents: 977
diff changeset
   168
    see the `user guide`_.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
   169
  * For more advanced tricks, see `sharing mutable history`_.
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   170
  * To learn about the concepts underlying ``evolve``, see `concepts`_
980
64a2e940e1b2 docs: add concepts guide (the set theory behind obsolescence)
Greg Ward <greg@gerg.ca>
parents: 979
diff changeset
   171
    (incomplete).
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   172
  * If you're coming from MQ, see the `MQ migration guide`_ (incomplete).
364
616305c63510 doc: cleanup in caveat and 2.1 compat
Pierre-Yves.David@ens-lyon.org
parents: 363
diff changeset
   173
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   174
.. _`user guide`: user-guide.html
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
   175
.. _`sharing mutable history`: sharing.html
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   176
.. _`concepts`: concepts.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
   177
.. _`MQ migration guide`: from-mq.html
3471
2a337fcedd5e doc: add link to roadmap
Boris Feld <boris.feld@octobus.net>
parents: 2962
diff changeset
   178
.. _`evolution roadmap in the wiki`: https://www.mercurial-scm.org/wiki/CEDRoadMap