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

README.rst 7.46 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
6
7
Evolve Extension
=================

Pierre-Yves David's avatar
Pierre-Yves David committed
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 Mercurial core,
Pierre-Yves David's avatar
Pierre-Yves David committed
18

19
* provides a set of commands to mutate your history,
Pierre-Yves David's avatar
Pierre-Yves David committed
20

21
22
* issues several warning messages when troubles from some mutable appears 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 exchanges and discovery during
27
  push and pull.
28

29
30
31
32
33
34
35
36
37
38
39
40
41
Documentation
-------------

We recommend reading the documentation first. An online version is
available here:

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

How to Install
==============

Using Pip
---------
42
43
44
45

You can install the latest evolution version usin pip::

    $ pip install --user hg-evolve
46

47
48
49
50
51
Then just enable it in you hgrc::

    $ hg config --edit # adds the two line below:
    [extensions]
    evolve =
Pierre-Yves David's avatar
Pierre-Yves David committed
52

53
54
From Source
-----------
55
56
57
58
59

To install a local version from source::

    $ hg clone https://www.mercurial-scm.org/repo/evolve/
    $ cd evolve
60
    $ pip install --user .
61
62
63
64
65
66
67
68
69

Then just enable it in you hgrc::

    $ hg config --edit # adds the two line below:
    [extensions]
    evolve =

Documentation lives in ``doc/``.

70
71
Server Only Setup
=================
72

73
74
75
76
It is possible to enable a smaller subset of the extensions aimed at server
serving repository. It skips the additions of the new commands and local UI
messages that might add performance overheads. To use the server only
extension, install the package and use::
77

78
    $ hg config --edit # adds the two line below:
79
    [extensions]
80
    evolve.serveronly =
81

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
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.
98

99
100
101
102
103
104
105
106
107
Python 3 support
================

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.

108
109
How to Contribute
=================
Pierre-Yves David's avatar
Pierre-Yves David committed
110

111
112
113
114
Discussion happens on the #hg-evolve IRC on freenode_.

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

115
116
117
Bugs are to be reported on the mercurial's bug tracker (component: `evolution`_):

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

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

123
124
125
126
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::
127

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


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

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

Please don't forget to update and run the tests when you fix a bug or
136
add a feature. To run the tests, you need a working copy of Mercurial,
137
say in $HGSRC::
138

139
140
    $ cd tests
    $ python $HGSRC/tests/run-tests.py
141

142
143
144
145
146
147
148
149
150
151
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.

152
153
154
Branch policy
-------------

155
156
The evolve tests are highly impacted by changes in core. To deal with this, we
use named branches.
157

158
159
160
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.
161

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

166
167
Test output changes from a changeset in core should add the following line to
their patch description:
168
169

CORE-TEST-OUTPUT-UPDATE: <CORE-NODE-ID>
170
171
172
173
174
175
176
177


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

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

178
.. _`format-source`: https://foss.heptapod.net/mercurial/format-source
179
180
181
182
183
184
185
186
187
188
189

Then update both your global and repo config files::

    $ hg config -l # add the lines below
    [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
190
191
192
193
194
195
196
197
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

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.