Merge lp:~james-w/launchpad/buildout-doc into lp:launchpad

[James Westby]

There is now documentation in doc/buildout.txt on using the "develop" setting to change a library and test it in launchpad.

Hi,

Here's some docs that Robert requested I write on using a branch
of a library as a dependency in Launchpad.

Thanks,

James

[Jonathan Lange (jml)]

Rockin'. Thanks.

review: Approve

=== modified file 'doc/buildout.txt'
--- doc/buildout.txt	2009-07-31 20:13:12 +0000
+++ doc/buildout.txt	2010-07-31 21:05:33 +0000
@@ -302,6 +302,8 @@
         develop = .
                   lazr_uri_branch
 
+    See `Developing a Dependent Library In Parallel`_ for more on this.
+
     The other basic key in the ``[buildout]`` section that we'll highlight here
     is ``parts``.  This key identifies the other sections in buildout.cfg that
     will be processed.  A section that is not identified in the ``[buildout]``
@@ -581,6 +583,51 @@
 
 .. _`the egg_info command`: http://peak.telecommunity.com/DevCenter/setuptools#tagging-and-daily-build-or-snapshot-releases
 
+Developing a Dependent Library In Parallel
+==========================================
+
+Sometimes you need to iterate on change to a library used by Launchpad
+that is managed by buildout as an egg. You could just edit what it is in
+the ``eggs`` directory, but it is harder to produce a patch while doing
+this. You could instead grab a branch of the libarary and produce an egg
+everytime you make a change and make buildout use the new egg, but this is
+slow.
+
+buildout defaults to only using the current directory as code that will
+be used without creating a distribution. We can arrange for it to use other
+paths as well, so we can use a checkout of any code we like, with changes
+being picked up instantly without us having to create a distribution.
+
+To do this add the extra paths to the ``develop`` key in the ``[buildout]``
+section of ``buildout.cfg"::
+
+    [buildout]
+    develop = .
+              path/to/branch
+
+and re-run ``make``.
+
+Now any changes you make in that path will be picked up, and you are free
+to make the changes you need and test them in the Launchpad environment.
+
+Once you are finished you can produce a distribution as above for inclusion
+in to Launchpad, as well as sending your patch upstream. At that point you
+are free to revert the configuration to only develop Launchpad. You should
+not submit your branch with this change in the configuration as it will
+not work for others.
+
+Be aware that you may have to change the version for the package in
+``versions.cfg`` if there is a difference between the version in the
+``eggs`` directory and the one in the ``setup.py`` that you pointed to
+in the ``develop`` key.
+
+One thing to be wary of is that setuptools treats "develop eggs" created
+by this process with the same precedence as system packages. That means
+that if the version in the ``setup.py`` at the path that you put in the
+``develop`` key is the same as the version installed system wide, setuptools
+may pick the wrong one. If that happens then increase the version in
+setup.py and setuptools will take it.
+
 =====================
 Possible Future Goals
 =====================