README

=============================
Mutable History For Mercurial
=============================

Evolve Extension
=================

This package supplies the ``evolve`` extension for Mercurial,

**The full implementation of the changeset evolution concept is still in
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.

This extension:

* enables the “changeset evolution” feature of Mercurial core,

* provides a set of commands to mutate your history,

* issues several warning messages when troubles from some mutable appears in
  your repository,

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

* improves performance of obsolescence marker exchanges and discovery during
  push and pull.

Documentation
-------------

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

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

Running Tests
=============

To run the tests, run ``tests/run-tests.py`` (from the Mercurial
sources) in the Evolve source directory. Before doing so, some steps
are required. Choose a location for your Mercurial sources. In what
followed, this will be referred to as ``/path/to/hg-repo``. All
commands (1) to (3) are run at the top level of the Evolve build
directory.

1) Download the Mercurial sources. E.g.

    $ hg clone https://www.mercurial-scm.org/repo/hg/ /path/to/hg-repo

3) Run

    $ /path/to/hg-repo/tests/run-tests.py

This will run the tests. You should see output similar to:

    Failed test-evolve-progress.t: output changed
    # Ran 155 tests, 5 skipped, 1 failed.

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

Using Pip
---------

You can install the latest evolution version usin pip::

    $ pip install --user hg-evolve

Then just enable it in you hgrc::

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

From Source
-----------

To install a local version from source::

    $ hg clone https://www.mercurial-scm.org/repo/evolve/
    $ cd evolve
    $ pip install --user .

Then just enable it in you hgrc::

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

Documentation lives in ``doc/``.

Debian package
--------------

1) To build the Debian package for a particular version, say 9.0.0 for
example, clone the Evolve sources from
https://www.mercurial-scm.org/repo/evolve/

Then make sure you are at the correct tag/version

    $ hg up -r 9.0.0

Then check that the most recent entry in ``debian/changelog``
corresponds to the version you want, in this case 9.0.0.

If the version you need is not present in the changelog, you can add
it with ``dch i``.

2) Then run

    $ make deb-prepare

at the top level of the sources. This will create an unpacked source
directory at the same level as the Evolve repository, ready for
building the Debian package. The make command will end with a line
like this, which says where the directory is located.

    debian build directory ready at /usr/local/src/mercurial-evolve/mercurial-evolve_9.0.0.orig

3) Then cd into that directory, and run a command to build the Debian
package. ``debuild`` is a good choice because it writes a build log
and also runs ``fakeroot`` for you. You need to install the
``debuild`` Debian package to use it. You may want to first make sure
that you have the necessary build dependencies installed, per the list
in ``debian/control``. You can install missing build dependencies by
running

    $ sudo apt-get build-dep .

at the top level of the Evolve sources. (``sudo apt build-dep .`` will
also work.) By default, the Debian build will run the Evolve tests.
Note that if any of the tests fail, the build will fail. If you want
to skip running the tests, pass the "nocheck" option to ``debuild`` to
skip the tests, as follows.

    $ DEB_BUILD_OPTIONS="nocheck" debuild -uc -us

To run the tests, ``debuild`` runs a script from the Mercurial sources
in the Evolve source directory. Details of running the tests are
contained in the section "Running Tests". Follow instructions (1) and
(2) in that section, then run

    $ debuild --set-envvar=HGSRC=/path/to/hg-repo -uc -us

This will build the package and also run the tests.

4) Once the build is complete, the deb package will be located one
level above the build directory. You can install it by doing

    $ sudo apt-get install ./mercurial-evolve_9.0.0-1_all.deb

(``sudo apt install`` will also work.)


Server Only Setup
=================

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

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

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.

How to Contribute
=================

Discussion happens on the #hg-evolve IRC on freenode_.

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

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

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

    $ hg email --to [email protected] --flag evolve-ext --rev '<your patches>'

Some of development happens on a public bitbucket repository (`evolve-devel`_) using the topic extension.

.. _`evolve-devel`: https://bitbucket.org/octobus/evolve-devel

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

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

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

    $ cd tests
    $ python $HGSRC/tests/run-tests.py

Branch policy
-------------

The evolve test are highly impacted by changes in core. To deal with this, we use named branches.

There are two main branches: "stable" and "default". Tests on these branch are
supposed to pass with the corresponding "default" and "stable" branch from core
Mercurial. The documentation is built from the tip of stable.

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

test output change from a changeset in core should adds the following line to their description:

CORE-TEST-OUTPUT-UPDATE: <CORE-NODE-ID>