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.6 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
39
40
41
42
43

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

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

Using Pip
---------
44

45
You can install the latest released version using pip::
46
47

    $ pip install --user hg-evolve
48

49
Then enable it in your hgrc::
50

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

55
56
From Source
-----------
57
58
59
60
61

To install a local version from source::

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

65
Then enable it in your hgrc::
66

67
    $ hg config --edit # add these two lines:
68
69
70
71
72
    [extensions]
    evolve =

Documentation lives in ``doc/``.

73
Server-only Setup
74
=================
75

76
77
78
79
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::
80

81
    $ hg config --edit # add these two lines:
82
    [extensions]
83
    evolve.serveronly =
84

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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.
101

102
Python 3 Support
103
104
105
106
107
108
109
110
================

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.

111
112
How to Contribute
=================
Pierre-Yves David's avatar
Pierre-Yves David committed
113

114
115
116
117
Discussion happens on the #hg-evolve IRC on freenode_.

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

118
119
Bugs are to be reported on the Mercurial's bug tracker (component:
`evolution`_).
120
121

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

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

127
128
129
130
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::
131

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

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

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

138
139
140
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::
141

142
143
    $ cd tests
    $ python $HGSRC/tests/run-tests.py
144

145
146
147
148
149
150
151
152
153
154
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.

155
156
157
Branch policy
-------------

158
159
The evolve tests are highly impacted by changes in core. To deal with this, we
use named branches.
160

161
162
163
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.
164

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

169
Test output changes from a changeset in core should add the following line to
170
their patch description::
171

172
    CORE-TEST-OUTPUT-UPDATE: <changeset hash>
173
174
175
176
177
178
179

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

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

180
.. _`format-source`: https://foss.heptapod.net/mercurial/format-source
181
182
183

Then update both your global and repo config files::

184
    $ hg config --local --edit # add these lines:
185
186
187
188
189
190
191
    [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
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
248
249

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.