This instance will be upgraded to Heptapod 0.26.0rc1 on 2021-10-26 at 14:00 UTC+2 (a few minutes of down time)

README.rst 7.77 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
96
97
98
99
100
101
102
103
104
105
106
107
Extension Purpose
=================

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

In addition, the evolve extensions support a wider set of Mercurial version,
allowing us to reach a larger user base for feedback. The Evolve extension is
not tight to the Mercurial release cycle and can release new feature and bug
fix at a higher rate if necessary.

Once a concept is ready enough, its implementation is moved into Mercurial
core. The maturation period helped us to get a clearer picture of what was
needed. During the upstreaming process, we can use this clearer picture to
clean up the code and upgrade it to an appropriate quality for Mercurial core.
108

109
Python 3 Support
110
111
112
113
114
115
116
117
================

Mercurial announced beta support for Python 3 starting with its 5.0 release.
Since 9.1.0, ``evolve`` has beta support for Python 3.6+.

Support will stay in beta while Mercurial's support for Python 3 remains in
beta and until it is a bit more battle-tested.

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

121
122
123
124
Discussion happens on the #hg-evolve IRC on freenode_.

.. _freenode: https://freenode.net/

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

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

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

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

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

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

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

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

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

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

162
163
164
Branch policy
-------------

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

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

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

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

179
    CORE-TEST-OUTPUT-UPDATE: <changeset hash>
180
181
182
183
184
185
186

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

Format source helps smooth out the pain of merging after auto-formatting.
Follow the instructions for install here:

187
.. _`format-source`: https://foss.heptapod.net/mercurial/format-source
188
189
190

Then update both your global and repo config files::

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

    [format-source]
    byteify-strings = python3 ~/workspace/octobus/mercurial-devel/contrib/byteify-strings.py --dictiter --treat-as-kwargs kwargs opts commitopts TROUBLES --allow-attr-methods
    byteify-strings:mode.input = file
    byteify-strings:mode.output = pipe
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
256

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.