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.5 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 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
Documentation
-------------

32
33
We recommend reading the documentation first. An online version is available
here:
34
35
36
37
38
39
40
41

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

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

Using Pip
---------
42

43
You can install the latest released version using pip::
44
45

    $ pip install --user hg-evolve
46

47
Then enable it in your hgrc::
48

49
    $ hg config --edit # add these two lines:
50
51
    [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
    # optionally `hg update <target revision>`
61
    $ pip install --user .
62

63
Then enable it in your hgrc::
64

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

Documentation lives in ``doc/``.

71
Server-only Setup
72
=================
73

74
75
76
77
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::
78

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

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

100
Python 3 Support
101
102
103
104
105
106
107
108
================

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.

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

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

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

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

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

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

125
126
127
128
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::
129

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

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

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

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

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

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

153
154
155
Branch policy
-------------

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

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

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

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

170
    CORE-TEST-OUTPUT-UPDATE: <changeset hash>
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

Then update both your global and repo config files::

182
    $ hg config --local --edit # add these lines:
183
184
185
186
187
188
189
    [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.