[ SEA-GHOST MINI SHELL]

Merge with Distribute
~~~~~~~~~~~~~~~~~~~~~

In 2013, the fork of Distribute was merged back into Setuptools. This
document describes some of the details of the merge.

.. toctree::
   :maxdepth: 2

   merge-faq

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.