# HG changeset patch # User Sushil khanchi # Date 1594228280 -19800 # Node ID b3e178f3e31fb77e8aa2654d611bf8e8d6685372 # Parent 03ce095dc10d455a9b0e0ef843bf61f7f29d1576 evolve: move README to rst diff -r 03ce095dc10d -r b3e178f3e31f README --- a/README Wed Jul 08 22:38:30 2020 +0530 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,247 +0,0 @@ -============================= -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 -`_ 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/ - -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/``. - -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. - -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. - -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=--- - -The recommended way is to create Merge Request on -https://foss.heptapod.net/mercurial/evolve. To do so, create an account and -request access. You'll then be able to create topic based merge request. - -Alternatively, you can use the patchbomb extension to send email to `mercurial -devel `_. -Please make sure to use the evolve-ext flag when doing so. You can use a -command like this:: - - $ hg email --to mercurial-devel@mercurial-scm.org --flag evolve-ext --rev '' - - -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 - -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. - -Branch policy -------------- - -The evolve tests 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 branches -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 versions of -Mercurial. They are the "mercurial-x.y" branches. They are used to apply -expected test changes only, no code changes should happen there. - -Test output changes from a changeset in core should add the following line to -their patch description: - -CORE-TEST-OUTPUT-UPDATE: - - -Format-source config -==================== - -Format source helps smooth out the pain of merging after auto-formatting. -Follow the instructions for install here: - -.. _`format-source`: https://bitbucket.org/octobus/format-source - -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 - -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. diff -r 03ce095dc10d -r b3e178f3e31f README.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.rst Wed Jul 08 22:41:20 2020 +0530 @@ -0,0 +1,247 @@ +============================= +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 +`_ 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/ + +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/``. + +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. + +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. + +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=--- + +The recommended way is to create Merge Request on +https://foss.heptapod.net/mercurial/evolve. To do so, create an account and +request access. You'll then be able to create topic based merge request. + +Alternatively, you can use the patchbomb extension to send email to `mercurial +devel `_. +Please make sure to use the evolve-ext flag when doing so. You can use a +command like this:: + + $ hg email --to mercurial-devel@mercurial-scm.org --flag evolve-ext --rev '' + + +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 + +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. + +Branch policy +------------- + +The evolve tests 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 branches +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 versions of +Mercurial. They are the "mercurial-x.y" branches. They are used to apply +expected test changes only, no code changes should happen there. + +Test output changes from a changeset in core should add the following line to +their patch description: + +CORE-TEST-OUTPUT-UPDATE: + + +Format-source config +==================== + +Format source helps smooth out the pain of merging after auto-formatting. +Follow the instructions for install here: + +.. _`format-source`: https://bitbucket.org/octobus/format-source + +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 + +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. diff -r 03ce095dc10d -r b3e178f3e31f setup.py --- a/setup.py Wed Jul 08 22:38:30 2020 +0530 +++ b/setup.py Wed Jul 08 22:41:20 2020 +0530 @@ -42,7 +42,7 @@ maintainer_email='pierre-yves.david@ens-lyon.org', url='https://www.mercurial-scm.org/doc/evolution/', description='Flexible evolution of Mercurial history.', - long_description=open(join(dirname(__file__), 'README')).read(), + long_description=open(join(dirname(__file__), 'README.rst')).read(), keywords='hg mercurial', license='GPLv2+', py_modules=py_modules,