docs/index.rst
author Pierre-Yves David <pierre-yves.david@octobus.net>
Fri, 09 Nov 2018 20:19:01 +0100
branchmercurial-4.3
changeset 4228 9a384c7a3b6a
parent 3471 2a337fcedd5e
child 5226 38d225efcea9
permissions -rw-r--r--
test-compat: merge mercurial-4.4 into mercurial-4.3
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