[Zope-CMF] A Tale of Two Repositories

[Tres Seaver]

Proposed Github-Launchpad Workflow for CMF
==========================================

A Tale of Two Repositories
--------------------------

.. blockquote::

   It was the best of times, it was the worst of times, it was the age
   of wisdom, it was the age of foolishness, it was the epoch of belief,
   it was the epoch of incredulity, it was the season of Light, it was
   the season of Darkness, it was the spring of hope, it was the winter
   of despair, we had everything before us, we had nothing before us, we
   were all going direct to Heaven, we were all going direct the other
   way – in short, the period was so far like the present period, that
   some of its noisiest authorities insisted on its being received, for
   good or for evil, in the superlative degree of comparison only.

At present, the various CMF projects (``Products.CMFCore``,
``Products.CMFDefault``, ``Products.CMFCalendar``,
``Products.CMFTopic``, ``Products.CMFUID``, ``Products.GenericSetup``)
are the only Zope Foundation projects actively maintained on
``svn.zope.org``:  all others have migrated to Github.  In the case that
any other previously-languishing project becomes active, it is first
moved to Github (e.g., [1]).

The CMF projects are in this state because one of the main developers is
unwilling to participate in the project if it moves entirely to
Github[2], but is willing to continue if a proposal is in place to
maintain a second public repository, against which his contributions
would be made[3].  This proposal aims to satisfy that request by hosting
the second, synchronized repository for each project using the new
Launchpad Git hosting option[4].

Repository Details
------------------

For each of the projects listed above:

1) Create a Git repository from its Subversion history, and push that
   repository to Github;  this step will use the same scripts used for
   other ZF repositories.  E.g., the branches, tags, and trunk for
   ``Products.CMFCore`` will be hosted on Github at
   https://github.com/zopefoundation/Products.CMFCore

2) Push the new Git repository also to Launchpad.  E.g., the same
   repository will be pushed to
   https://code.launchpad.net/~zope-cmf/Products.CMFCore

3) Remove all entries from the project's trunk and active release
   branches on ``svn.zope.org``, leaving behind only a

4) Add one-way synchronization ("mirroring") from the Github repository
   to the Launchpad repository, with the synch happening on a
   ZF-maintained host.  This explicit syncronization can be retired once
   the Launchpad Git integration has added its own mirroring (already
   announced as underway on [4]).

Contributor Workflow:  Github
-----------------------------

Github-based contributors will follow normal Github workflow patterns:

- Fork the repository of interest via the Github UI.

- Check out the fork, e.g.:

.. code-block:: bash

   $ git clone git at github.com:username/Products.CMFCore
   $ cd Products.CMFCore

- Make their changes on a branch, test them, and commit.

.. code-block:: bash

   $ git checkout -b bug-12345 master
   $ vim Products/CMFCore/DynamicType.py
   ...
   $ tox
   ...
   $ git commit -am "Clean up dyanmic types.

   Fixes #12345"

- Push the changed branch back to their fork on Github:

.. code-block:: bash

   $ git push origin bug-12345

- Create a pull request from the branch of their fork to the appropriate
  master / release branch of ZF's repository via the Github UI.

Contributor Workflow:  Launchpad
--------------------------------

Launchpad-based contributors will follow normal Launchpad workflow
patterns.  (URLs below assume the contributor has applied the Git
configuration described in the "Configuring Git" section of [4]).

- Clone the repository, e.g.:

.. code-block:: bash

   $ git clone lp:Products.CMFCore
   $ cd Products.CMFCore

- Make their changes on a branch, test them, and commit.

.. code-block:: bash

   $ git checkout -b bug-12345 master
   $ vim Products/CMFCore/DynamicType.py
   ...
   $ tox
   ...
   $ git commit -am "Clean up dyanmic types.

   Fixes #12345"

- Push the changed branch back to their fork on Launchad:

.. code-block:: bash

   $ git push lpme:Products.CMFCore

- Create a merge proposal from the branch of their fork to the
  appropriate master / release branch of ZF's repository via the LP UI.

Maintainer Workflow:  Github
-----------------------------

Maintainers will work with the Github repository as the "primary"
repository for a CMF project, using the normal patterns for other ZF
repositories hosted at Github (checking for contributor status, etc.)

- The canonical location for bug reports will be on Github.

- We will enable continuous integration for pull requests and merges via
  Travis-CI.

- After review by a maintainer, and assuming the CI passes, the
  maintainer may merge pull requests via the Github UI of via the
  command line.

- Releases will be made from the maintainer's clone of the Github
  repository, after creating and pushing the appropriate tag for the
  release.

Maintainer Workflow:  Launchpad
-------------------------------

When reviewing a Launchpad merge proposal, the maintainers fetches the
proposed branch, e.g.:

.. code-block:: bash

   $ cd ~/projects/CMF/Products.CMFCore
   $ git checkout -b contributor-bug-12345 master
   $ git pull lp:~contributor/+git/Products.CMFCore bug-12345

and reviews / tests it locally, e.g.:

.. code-block:: bash

   $ git log -p
   $ tox

Once review and testing are complete, the maintainer merges the
branch via the command line, e.g.:

.. code-block:: bash

   $ git checkout master
   $ git merge --no-ff contributor-bug-12345

The maintainer pushes the target branch *to Github only*, e.g.:

.. code-block:: bash

   $ git remote -v | grep origin
   origin	git at github.com:zopefoundation/gcloud-python.git (fetch)
   origin	git at github.com:zopefoundation/gcloud-python.git (push)
   $ git push origin master

The Launchpad repository will be synched automatically, whether by the
cron job or by the built-in Launchpad mirroring.

References
----------

[1] http://comments.gmane.org/gmane.comp.web.zope.devel/30569

[2] http://permalink.gmane.org/gmane.comp.web.zope.cmf/18242

[3] http://permalink.gmane.org/gmane.comp.web.zope.cmf/19025

[4] https://help.launchpad.net/Code/Git


-- 
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com