README.rst 7.73 KB
Newer Older
Pierre-Yves David's avatar
Pierre-Yves David committed
1
=============================
Pierre-Yves David's avatar
Pierre-Yves David committed
2
3
4
Mutable History For Mercurial
=============================

5
Evolve Extension
6
================
7

8
This package supplies the evolve extension for Mercurial,
Pierre-Yves David's avatar
Pierre-Yves David committed
9

Pierre-Yves David's avatar
Pierre-Yves David committed
10
**The full implementation of the changeset evolution concept is still in
11
12
13
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.
Pierre-Yves David's avatar
Pierre-Yves David committed
14

15
This extension:
Pierre-Yves David's avatar
Pierre-Yves David committed
16

17
* enables the "`changeset evolution`_" feature of core Mercurial,
Pierre-Yves David's avatar
Pierre-Yves David committed
18

19
* provides a set of commands to rewrite history in a distributed way,
Pierre-Yves David's avatar
Pierre-Yves David committed
20

21
22
* issues various warning messages when "troubles" from changeset evolution
  appear in your repository,
Pierre-Yves David's avatar
Pierre-Yves David committed
23

24
* provides an ``hg evolve`` command to deal with such troubles,
25

26
* improves performance of obsolescence marker exchange and discovery during
27
  push and pull.
28

29
30
.. _`changeset evolution`: https://www.mercurial-scm.org/wiki/ChangesetEvolution

31
32
33
Documentation
-------------

34
35
We recommend reading the documentation first. An online version is available
here:
36
37
38

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

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

41
42
43
44
45
How to Install
==============

Using Pip
---------
46

47
You can install the latest released version using pip::
48
49

    $ pip install --user hg-evolve
50

51
Then enable it in your hgrc::
52

53
    $ hg config --edit # add these two lines:
54
55
    [extensions]
    evolve =
Pierre-Yves David's avatar
Pierre-Yves David committed
56

57
58
From Source
-----------
59
60
61
62
63

To install a local version from source::

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

67
Then enable it in your hgrc::
68

69
    $ hg config --edit # add these two lines:
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
78

79
Server-only Setup
80
=================
81

82
83
It is possible to enable a smaller subset of the features aimed at servers that
simply serve repositories::
84

85
    $ hg config --edit # add these two lines:
86
    [extensions]
87
    evolve.serveronly =
88

89
90
91
It skips the additions of the new commands and local UI messages that might add
performance overhead.

92
93
94
95
Extension Purpose
=================

The goal of this extension is to provide an appropriate place for code and
96
97
concepts related to `changeset evolution`_ to mature. In this extension we
allow hackier code, unlocking quick experimentation and faster iterations.
98

99
100
101
102
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.
103

104
105
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
106
needed. During the upstreaming process, we can use this clearer picture to
107
clean up the code and upgrade it to an appropriate quality for core Mercurial.
108

109
Python 3 Support
110
111
================

112
113
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+.
114

115
.. _`support for Python 3`: https://www.mercurial-scm.org/wiki/Python3
116

117
118
How to Contribute
=================
Pierre-Yves David's avatar
Pierre-Yves David committed
119

120
Discussion happens on the #hg-evolve IRC on libera_.
121

122
.. _libera: https://libera.chat/
123

124
125
Bugs are to be reported on the Mercurial's bug tracker (component:
`evolution`_).
126
127

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

129
The recommended way to submit a patch is to create a Merge Request on
Anton Shestakov's avatar
Anton Shestakov committed
130
https://foss.heptapod.net/mercurial/evolve. To do so, create an account and
131
request access. You'll then be able to create a topic-based merge request.
132

133
134
135
136
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::
137

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

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

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

144
145
146
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::
147

148
149
    $ cd tests
    $ python $HGSRC/tests/run-tests.py
150

151
152
153
154
155
156
157
158
159
160
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.

161
162
163
Branch policy
-------------

164
165
The evolve tests are highly impacted by changes in core Mercurial. To deal with
this, we use named branches.
166

167
168
169
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.
170

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

175
Test output changes from a changeset in core should add the following line to
176
their patch description::
177

178
    CORE-TEST-OUTPUT-UPDATE: <changeset hash>
179
180
181
182

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

183
184
Format-source helps smooth out the pain of merging after auto-formatting.
Follow the installation instructions at the `format-source`_ repo.
185

186
.. _`format-source`: https://foss.heptapod.net/mercurial/format-source
187

188
Then update your per-repo config file::
189

190
    $ hg config --local --edit # add these lines:
191
192
193
194
    [extensions]
    formatsource =

    [format-source]
195
    byteify-strings = python3 ~/hg/contrib/byteify-strings.py --dictiter --treat-as-kwargs kwargs opts commitopts TROUBLES --allow-attr-methods
196
197
    byteify-strings:mode.input = file
    byteify-strings:mode.output = pipe
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

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

* make sure the tests are happy on all supported versions,

  You can use the `contrib/merge-test-compat.sh` to merge with the test
  compatibility branches.

* make sure there is no code difference between the compat branches and stable
  (no diff within `hgext3rd/`),

* update the `testedwith` variable for all extensions (remove '.dev'):

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

* make sure the changelog is up to date,

* add a date to the changelog entry for the target version,

* update the `__version__` field of all relevant extensions:

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

* create a new Debian entry:

  - 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,

* push and publish the tag,

* upload the tarball to PyPI,

* make an announcement on evolve-testers@mercurial-scm.org (possibly on
  mercurial@mercurial-scm.org too),

* bump versions of all extensions and add '.dev' (see existing commits as an
  example):

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

  The version we use on the stable branch during development should be
  `x.y.z+1.dev`. The version of the default branch should be `x.y+1.0.dev`.

* merge stable into default.