Migration guide from legacy garden packages

Guide for migrating existing garden packages to the new for using proper python package structure.

• Demo converting pure-python graph from https://github.com/kivy-garden/garden.graph to https://github.com/kivy-garden/graph
• Demo converting cython-python collider from https://github.com/kivy-garden/garden.collider to https://github.com/kivy-garden/collider

Here are the demo pure-python and cython-python flowers to be used as starting points for new flowers and for the migration.

Guide

The following steps use the garden graph package to demonstrate how to migrate a package to the new format.

1. Create a new empty repo with the name graph in garden.

2. In coveralls sync the kivy-garden repos and then enable it.

3. Clone the flower demo repo, if you haven't already. Otherwise make sure it is up to date with master: For a pure python flower:

   git clone git@github.com:kivy-garden/flower.git

   or for a cython-python flower:

   git clone git@github.com:kivy-garden/cython_flower.git

4. Push the flower repo to github:

   cd flower
   git push --mirror git@github.com:kivy-garden/graph.git

5. Now clone graph and the original garden.graph locally:

   git clone git@github.com:kivy-garden/graph.git
   git clone git@github.com:kivy-garden/garden.graph.git

6. Merge garden.graph into the new graph:

   cd graph
   git remote add original ../garden.graph
   git remote update
   git merge --allow-unrelated-histories original/master

   If there are any merge conflicts, resolve them and commit.

7. Migrate the original package structure into a pythonic structure.

   1. Remove the kivy-garden/flower directory and make a new kivy-garden/graph directory.
   2. Copy all the original python modules e.g. __init__.py into kivy-garden/graph.
   3. Fix the tests in tests/ to test the graph code.
   4. open setup.py and replace all instances of flower with graph.
   5. Do any remaining cleanup, e.g. duplicate license files or readme.
   6. Commit all changes.

8. Test to make sure everything works, otherwise fix and commit (make sure pytest is installed). Test install it to python and use it in your app:

   pip install .
   python -c "from kivy_garden.graph import Graph"

   If it's a cython flower (graph isn't), compile it first:

   PYTHONPATH=.:$PYTHONPATH python setup.py build_ext --inplace

   Then run the tests:

   PYTHONPATH=. python -m pytest tests/

9. Push to kivy-garden and remove the original garden remote

   git push origin master
   git remote rm original

10. Verify that the travis tests pass.

11. Archive garden.graph