Mercurial > evolve

annotate docs/index.rst @ 2894:31aa9d097d29

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: record all the missings and strange bit we know We know the doc is not as fresh as it could be. We make sure the reader is aware too.
author Pierre-Yves David <pierre-yves.david@octobus.net>
date Wed, 30 Aug 2017 18:35:04 +0200
parents c1cf3c8947f1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
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
2894
31aa9d097d29 doc: record all the missings and strange bit we know
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2887
diff changeset
57 known-doc-issues
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
58
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
59 .. _`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
60
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
61 What is Changeset Evolution?
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
62 ----------------------------
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
63
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
64 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
65 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
66 modify or remove old changesets.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
67
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
68 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
69 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
70 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
71 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
72 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
73
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
74 ``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
75 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
76 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
77 operation.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
78
2872
78debdfb3e4d doc: simplify the reference to in-core features
Philippe Pepiot <phil@philpep.org>
parents: 2871
diff changeset
79 ``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
80
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
81 * *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
82 mutable and immutable changesets.
227
abe52cf492ee doc: several update and review.
Pierre-Yves.David@ens-lyon.org
parents: 194
diff changeset
83
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
84 * *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
85 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
86 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
87 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
88 *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
89 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
90 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
91
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
92 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
93
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
94 * 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
95 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
96 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
97 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
98
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
99 * 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
100 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
101 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
102 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
103
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
104 * 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
105 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
106 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
107
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
108 * 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
109 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
110 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
111 ``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
112 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
113 testing on the test server.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
114
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
115 * 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
116 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
117 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
118 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
119
2881
9b270ce3763b doc-front-page: expand the paragraph about changeset evolution
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2880
diff changeset
120 * 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
121 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
122 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
123 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
124
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
125 Why the `evolve` extension?
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
126 ---------------------------
2882
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
127
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
128 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
129 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
130
4b7252600e57 doc-front-pagE: add a paragraph about "why the extension"
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 2881
diff changeset
131 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
132 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
133 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
134 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
135 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
136
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
137 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
138 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
139
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
140 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
141 ------------------
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
142
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
143 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
144 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
145 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
146 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
147 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
148 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
149
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
150 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
151 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
152 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
153 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
154 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
155 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
156 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
157 by the new default.
166
8f8a52cd0b9f big doc update
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 165
diff changeset
158
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
159 .. # .. _`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
160
2887
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
161 Resources
c1cf3c8947f1 index: edit pass by native english speaker
Ryan McElroy <rmcelroy@fb.com>
parents: 2884
diff changeset
162 ---------
1266
c94aaf6df69c docs: flesh out unfinished bits in the intro page
Greg Ward <greg@gerg.ca>
parents: 980
diff changeset
163
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
164 * 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
165 see the `user guide`_.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents: 978
diff changeset
166 * 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
167 * 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
168 (incomplete).
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
169 * 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
170
977
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
171 .. _`user guide`: user-guide.html
1284
e33990a4c27a docs: add a table of contents
Greg Ward <greg@gerg.ca>
parents: 1266
diff changeset
172 .. _`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
173 .. _`concepts`: concepts.html
cc0f0d94bf30 docs: rewrite index page (including dangling links to future docs)
Greg Ward <greg@gerg.ca>
parents: 709
diff changeset
174 .. _`MQ migration guide`: from-mq.html