README.rst 8.35 KB
Newer Older
Sushil Khanchi's avatar
Sushil Khanchi committed
1
2
3
4
5
=============================
Mutable History For Mercurial
=============================

Evolve Extension
6
================
Sushil Khanchi's avatar
Sushil Khanchi committed
7

8
This package supplies the evolve extension for Mercurial,
Sushil Khanchi's avatar
Sushil Khanchi committed
9
10
11
12
13
14
15
16

**The full implementation of the changeset evolution concept is still in
progress.**  Please subscribe to the `evolve-testers mailing list
<https://www.mercurial-scm.org/mailman/listinfo/evolve-testers>`_ to stay up to
date with changes.

This extension:

17
* enables the "`changeset evolution`_" feature of core Mercurial,
Sushil Khanchi's avatar
Sushil Khanchi committed
18

19
20
21
22
* provides a set of commands to rewrite history in a distributed way,

* issues various warning messages when "troubles" from changeset evolution
  appear in your repository,
Sushil Khanchi's avatar
Sushil Khanchi committed
23

24
* provides an ``hg evolve`` command to deal with such troubles,
Sushil Khanchi's avatar
Sushil Khanchi committed
25

26
27
* improves performance of obsolescence marker exchange and discovery during
  push and pull.
Sushil Khanchi's avatar
Sushil Khanchi committed
28

29
.. _`changeset evolution`: https://www.mercurial-scm.org/wiki/ChangesetEvolution
Sushil Khanchi's avatar
Sushil Khanchi committed
30
31
32
33

Documentation
-------------

34
35
We recommend reading the documentation first. An online version is available
here:
Sushil Khanchi's avatar
Sushil Khanchi committed
36
37
38

    https://www.mercurial-scm.org/doc/evolution/

39
40
Source of the documentation can be found in ``docs/``.

Sushil Khanchi's avatar
Sushil Khanchi committed
41
42
43
44
45
46
How to Install
==============

Using Pip
---------

47
You can install the latest released version using pip::
Sushil Khanchi's avatar
Sushil Khanchi committed
48
49
50

    $ pip install --user hg-evolve

51
Then enable it in your hgrc::
Sushil Khanchi's avatar
Sushil Khanchi committed
52

53
    $ hg config --edit # add these two lines:
Sushil Khanchi's avatar
Sushil Khanchi committed
54
55
56
57
58
59
60
61
62
63
    [extensions]
    evolve =

From Source
-----------

To install a local version from source::

    $ hg clone https://www.mercurial-scm.org/repo/evolve/
    $ cd evolve
64
    # optionally `hg update <target revision>`
Sushil Khanchi's avatar
Sushil Khanchi committed
65
66
    $ pip install --user .

67
Then enable it in your hgrc::
Sushil Khanchi's avatar
Sushil Khanchi committed
68

69
    $ hg config --edit # add these two lines:
Sushil Khanchi's avatar
Sushil Khanchi committed
70
71
72
    [extensions]
    evolve =

73
74
75
76
77
It's also possible to use evolve without installing it, in which case you will
need to provide the full path to ``hgext3rd/evolve/``, for example::

    [extensions]
    evolve = ~/evolve/hgext3rd/evolve
Sushil Khanchi's avatar
Sushil Khanchi committed
78

79
80
81
82
83
84
85
86
87
88
89
Pitfalls
--------

If you get ``"failed to import extension evolve: No module named 'evolve'"``
error, there are a couple of things to check:

* make sure you gave pip the correct package name (it's hg-evolve),

* make sure evolve is installed for the same version of Python that you use for
  running Mercurial (``hg debuginstall | grep Python``).

90
Server-only Setup
Sushil Khanchi's avatar
Sushil Khanchi committed
91
92
=================

93
94
It is possible to enable a smaller subset of the features aimed at servers that
simply serve repositories::
Sushil Khanchi's avatar
Sushil Khanchi committed
95

96
    $ hg config --edit # add these two lines:
Sushil Khanchi's avatar
Sushil Khanchi committed
97
98
99
    [extensions]
    evolve.serveronly =

100
101
102
It skips the additions of the new commands and local UI messages that might add
performance overhead.

Sushil Khanchi's avatar
Sushil Khanchi committed
103
104
105
106
Extension Purpose
=================

The goal of this extension is to provide an appropriate place for code and
107
108
concepts related to `changeset evolution`_ to mature. In this extension we
allow hackier code, unlocking quick experimentation and faster iterations.
Sushil Khanchi's avatar
Sushil Khanchi committed
109

110
111
112
113
In addition, evolve extension supports a wide range of Mercurial versions,
allowing us to reach a larger user base for feedback. The extension is not tied
to the Mercurial release cycle and can release new features and bug fixes at a
higher rate if necessary.
Sushil Khanchi's avatar
Sushil Khanchi committed
114

115
116
Once a concept is deemed ready, its implementation is moved into core
Mercurial. The maturation period helped us to get a clearer picture of what was
Sushil Khanchi's avatar
Sushil Khanchi committed
117
needed. During the upstreaming process, we can use this clearer picture to
118
clean up the code and upgrade it to an appropriate quality for core Mercurial.
Sushil Khanchi's avatar
Sushil Khanchi committed
119

120
Python 3 Support
Sushil Khanchi's avatar
Sushil Khanchi committed
121
122
================

123
124
Mercurial announced official `support for Python 3`_ starting with its 5.2
release. Since 9.3.0, evolve has official support for Python 3.6+.
Sushil Khanchi's avatar
Sushil Khanchi committed
125

126
.. _`support for Python 3`: https://www.mercurial-scm.org/wiki/Python3
Sushil Khanchi's avatar
Sushil Khanchi committed
127

128
129
130
131
132
133
134
135
136
Python 2 Support
================

Python 2 is supported by evolve. However, Mercurial 6.2 release dropped support
for it, so evolve can work on Python 2 only on earlier versions.

Debian packages that are built using Heptapod CI only install files for Python
3, because they target current Debian stable.

Sushil Khanchi's avatar
Sushil Khanchi committed
137
138
139
How to Contribute
=================

140
Discussion happens in #hg-evolve and #mercurial on libera_ IRC network.
Sushil Khanchi's avatar
Sushil Khanchi committed
141

142
.. _libera: https://libera.chat/
Sushil Khanchi's avatar
Sushil Khanchi committed
143

144
145
Bugs are to be reported on the Mercurial's bug tracker (component:
`evolution`_).
Sushil Khanchi's avatar
Sushil Khanchi committed
146
147
148

.. _evolution: https://bz.mercurial-scm.org/buglist.cgi?component=evolution&query_format=advanced&resolution=---

149
The recommended way to submit a patch is to create a Merge Request on
Sushil Khanchi's avatar
Sushil Khanchi committed
150
https://foss.heptapod.net/mercurial/evolve. To do so, create an account and
151
request access. You'll then be able to create a topic-based merge request.
Sushil Khanchi's avatar
Sushil Khanchi committed
152
153
154
155
156
157
158
159
160
161
162
163

Alternatively, you can use the patchbomb extension to send email to `mercurial
devel <https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel>`_.
Please make sure to use the evolve-ext flag when doing so. You can use a
command like this::

    $ hg email --to mercurial-devel@mercurial-scm.org --flag evolve-ext --rev '<your patches>'

For guidelines on the patch description, see the `official Mercurial guideline`_.

.. _`official Mercurial guideline`: https://mercurial-scm.org/wiki/ContributingChanges#Patch_descriptions

164
165
166
Please don't forget to update and run the tests when you fix a bug or add a
feature. To run the tests, you need a working copy of Mercurial, say in
$HGSRC::
Sushil Khanchi's avatar
Sushil Khanchi committed
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183

    $ cd tests
    $ python $HGSRC/tests/run-tests.py

When certain blocks of code need to cope with API changes in core Mercurial,
they should have comments in the ``hg <= x.y (commit hash)`` format. For
example, if a function needs another code path because of changes introduced in
02802fa87b74 that was first included in Mercurial 5.3, then the comment should
be::

    # hg <= 5.2 (02802fa87b74)

See also tests/test-check-compat-strings.t.

Branch policy
-------------

184
185
The evolve tests are highly impacted by changes in core Mercurial. To deal with
this, we use named branches.
Sushil Khanchi's avatar
Sushil Khanchi committed
186
187
188
189
190
191
192
193
194
195

There are two main branches: "stable" and "default". Tests on these branches
are supposed to pass with the corresponding "default" and "stable" branch from
core Mercurial. The documentation is built from the tip of stable.

In addition, we have compatibility branches to check tests on older versions of
Mercurial. They are the "mercurial-x.y" branches. They are used to apply
expected test changes only, no code changes should happen there.

Test output changes from a changeset in core should add the following line to
196
their patch description::
Sushil Khanchi's avatar
Sushil Khanchi committed
197

198
    CORE-TEST-OUTPUT-UPDATE: <changeset hash>
Sushil Khanchi's avatar
Sushil Khanchi committed
199
200
201
202

Format-source config
====================

203
204
Format-source helps smooth out the pain of merging after auto-formatting.
Follow the installation instructions at the `format-source`_ repo.
Sushil Khanchi's avatar
Sushil Khanchi committed
205

206
.. _`format-source`: https://foss.heptapod.net/mercurial/format-source
Sushil Khanchi's avatar
Sushil Khanchi committed
207

208
Then update your per-repo config file::
Sushil Khanchi's avatar
Sushil Khanchi committed
209

210
    $ hg config --local --edit # add these lines:
Sushil Khanchi's avatar
Sushil Khanchi committed
211
212
213
214
    [extensions]
    formatsource =

    [format-source]
215
    byteify-strings = python3 ~/hg/contrib/byteify-strings.py --dictiter --treat-as-kwargs kwargs opts commitopts TROUBLES --allow-attr-methods
Sushil Khanchi's avatar
Sushil Khanchi committed
216
217
218
219
220
221
    byteify-strings:mode.input = file
    byteify-strings:mode.output = pipe

Release Checklist
=================

222
223
224
* use contrib/merge-test-compat.sh to merge with the test compatibility
  branches,

Sushil Khanchi's avatar
Sushil Khanchi committed
225
226
* make sure the tests are happy on all supported versions,

227
228
* make sure there is no code difference between the compatibility branches and
  stable (no diff within hgext3rd/),
Sushil Khanchi's avatar
Sushil Khanchi committed
229

230
* update the ``testedwith`` variable for all extensions (remove '.dev'):
Sushil Khanchi's avatar
Sushil Khanchi committed
231
232
233
234
235

  - hgext3rd/evolve/metadata.py
  - hgext3rd/topic/__init__.py
  - hgext3rd/pullbundle.py

236
* make sure CHANGELOG is up-to-date,
Sushil Khanchi's avatar
Sushil Khanchi committed
237

238
* add a date to the CHANGELOG entry for the target version,
Sushil Khanchi's avatar
Sushil Khanchi committed
239

240
* update the ``__version__`` field of all relevant extensions:
Sushil Khanchi's avatar
Sushil Khanchi committed
241
242
243
244
245

  - hgext3rd/evolve/metadata.py
  - hgext3rd/topic/__init__.py
  - hgext3rd/pullbundle.py (if touched)

246
* create a new Debian changelog entry:
Sushil Khanchi's avatar
Sushil Khanchi committed
247
248
249
250
251
252
253
254
255
256
257

  - debchange --newversion x.y.z-1 "new upstream release"
  - debchange --release

* sanity check install and sdist targets of setup.py:

  - python setup.py install --home=$(mktemp -d)
  - python setup.py sdist

* tag the commit,

258
259
* move ``@`` bookmark to the new tag,

Sushil Khanchi's avatar
Sushil Khanchi committed
260
261
262
263
* push and publish the tag,

* upload the tarball to PyPI,

264
265
* make an announcement on evolve-testers@mercurial-scm.org and
  mercurial@mercurial-scm.org,
Sushil Khanchi's avatar
Sushil Khanchi committed
266

267
* bump versions of all extensions and add ``.dev`` (see existing commits as an
Sushil Khanchi's avatar
Sushil Khanchi committed
268
269
270
271
272
273
  example):

  - hgext3rd/evolve/metadata.py
  - hgext3rd/topic/__init__.py
  - hgext3rd/pullbundle.py

274
275
276
277
  Version bump rules:

  - stable branch x.y.z+1.dev
  - default branch x.y+1.0.dev
Sushil Khanchi's avatar
Sushil Khanchi committed
278
279

* merge stable into default.