Moved MERGE.txt into the setuptools documentation.

--HG--
rename : MERGE.txt => docs/merge.txt

2 files changed, 118 insertions, 0 deletions

diff --git a/docs/index.txt b/docs/index.txt
index 21442b93..162a5f6f 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -16,6 +16,7 @@ Documentation content:
 .. toctree::
    :maxdepth: 2
 
+   merge
    roadmap
    python3
    using
diff --git a/docs/merge.txt b/docs/merge.txt
new file mode 100644
index 00000000..23d1e857
--- /dev/null
+++ b/docs/merge.txt
@@ -0,0 +1,117 @@
+Merge with Distribute
+~~~~~~~~~~~~~~~~~~~~~
+
+In 2013, the fork of Distribute was merged back into Setuptools. This
+document describes some of the details of the merge.
+
+Process
+=======
+
+In order to try to accurately reflect the fork and then re-merge of the
+projects, the merge process brought both code trees together into one
+repository and grafted the Distribute fork onto the Setuptools development
+line (as if it had been created as a branch in the first place).
+
+The rebase to get distribute onto setuptools went something like this::
+
+    hg phase -d -f -r 26b4c29b62db
+    hg rebase -s 26b4c29b62db -d 7a5cf59c78d7
+
+The technique required a late version of mercurial (2.5) to work correctly.
+
+The only code that was included was the code that was ancestral to the public
+releases of Distribute 0.6. Additionally, because Setuptools was not hosted
+on Mercurial at the time of the fork and because the Distribute fork did not
+include a complete conversion of the Setuptools history, the Distribute
+changesets had to be re-applied to a new, different conversion of the
+Setuptools SVN repository. As a result, all of the hashes have changed.
+
+Distribute was grafted in a 'distribute' branch and the 'setuptools-0.6'
+branch was targeted for the merge. The 'setuptools' branch remains with
+unreleased code and may be incorporated in the future.
+
+Reconciling Differences
+=======================
+
+There were both technical and philosophical differences between Setuptools
+and Distribute. To reconcile these differences in a manageable way, the
+following technique was undertaken:
+
+Create a 'Setuptools-Distribute merge' branch, based on a late release of
+Distribute (0.6.35). This was done with a00b441856c4.
+
+In that branch, first remove code that is no longer relevant to
+Setuptools (such as the setuptools patching code).
+
+Next, in the the merge branch, create another base from at the point where the
+fork occurred (such that the code is still essentially an older but pristine
+setuptools). This base can be found as 955792b069d0. This creates two heads
+in the merge branch, each with a basis in the fork.
+
+Then, repeatedly copy changes for a
+single file or small group of files from a late revision of that file in the
+'setuptools-0.6' branch (1aae1efe5733 was used) and commit those changes on
+the setuptools-only head. That head is then merged with the head with
+Distribute changes. It is in this Mercurial
+merge operation that the fundamental differences between Distribute and
+Setuptools are reconciled, but since only a single file or small set of files
+are used, the scope is limited.
+
+Finally, once all the challenging files have been reconciled and merged, the
+remaining changes from the setuptools-0.6 branch are merged, deferring to the
+reconciled changes (a1fa855a5a62 and 160ccaa46be0).
+
+Originally, jaraco attempted all of this using anonymous heads in the
+Distribute branch, but later realized this technique made for a somewhat
+unclear merge process, so the changes were re-committed as described above
+for clarity. In this way, the "distribute" and "setuptools" branches can
+continue to track the official Distribute changesets.
+
+Concessions
+===========
+
+With the merge of Setuptools and Distribute, the following concessions were
+made:
+
+Differences from setuptools 0.6c12:
+
+Major Changes
+-------------
+
+* Python 3 support.
+* Improved support for GAE.
+* Support `PEP-370 <http://www.python.org/dev/peps/pep-0370/>`_ per-user site
+  packages.
+* Sort order of Distributions in pkg_resources now prefers PyPI to external
+  links (Distribute issue 163).
+* Python 2.4 or greater is required (drop support for Python 2.3).
+
+Minor Changes
+-------------
+
+* Wording of some output has changed to replace contractions with their
+  canonical form (i.e. prefer "could not" to "couldn't").
+* Manifest files are only written for 32-bit .exe launchers.
+
+Differences from Distribute 0.6.36:
+
+Major Changes
+-------------
+
+* The _distribute property of the setuptools module has been removed.
+* Distributions are once again installed as zipped eggs by default, per the
+  rationale given in `the seminal bug report
+  <http://bugs.python.org/setuptools/issue33>`_ indicates that the feature
+  should remain and no substantial justification was given in the `Distribute
+  report <https://bitbucket.org/tarek/distribute/issue/19/>`_.
+
+Minor Changes
+-------------
+
+* The patch for `#174 <https://bitbucket.org/tarek/distribute/issue/174>`_
+  has been rolled-back, as the comment on the ticket indicates that the patch
+  addressed a symptom and not the fundamental issue.
+* ``easy_install`` (the command) once again honors setup.cfg if found in the
+  current directory. The "mis-behavior" characterized in `#99
+  <https://bitbucket.org/tarek/distribute/issue/99>`_ is actually intended
+  behavior, and no substantial rationale was given for the deviation.