Policy for Documenting Custom Distributions

Problem

Sometimes we need to make custom, local distributions of packages that we use. We want all developers to know how to get an original copy of the code that we are using for our distributions, so that we can all make subsequent changes and releases, and we can all try to push patches upstream.

Why do we sometimes need to make custom distributions?

• We need bugfixes or changes in trunk or some other branch upstream.
• Upstream does not provide a distribution.
• Upstream has not accepted patches we need.

Here are some concrete examples from recent Launchpad usage.

feedvalidator

• Does not provide a distribution other than nightly versions without differing version numbers.

• Has needed a patch. They have not replied to our requests to discuss. http://groups.google.com/group/feedvalidator-users/browse_thread/thread/e6a3bab8d665b501

zc.buildout, zc.recipe.egg, z3c.recipe.filetemplate

We have contributed changes to make these packages work more smoothly with a system Python. They are in branches in the zope.org repository, awaiting review.

Storm

• We have patched Storm locally and made a local distribution.
• We have also used a local distribution of trunk.

Considerations

Do we need to keep all branches in Launchpad, or is it acceptable to defer to canonical upstream repositories for a given project?

The current proposed solution specifies that it is OK to defer to upstream repositories.

Proposed Solution

versions.cfg (in the top level of the Launchpad tree) is where we specify our versions. Whenever we add a custom local distribution there, we should precede it with at least three comment lines.

The first should indicate the location of the sourcecode (trunk or branch or tag), that was used to create the distribution. The location may be in Launchpad or in the canonical upstream repository for the code, if it uses bzr, git, hg, or svn (excluding cvs because I suspect many of us have forgotten how to work with it.

The second should indicate the revision number of the sourcecode.

The last comment lines should show the exact command(s) used to generate the local distribution from the given branch. This can be important because of setuptools flags like -r and -b that allow you to change the effective version identifier.

The idea is that another developer should be able to check out the sourcecode at the given revision id and run the listed command to get an exact copy of the custom distribution we are using.