wiki:DevelopmentEnvironment
Last modified 13 days ago

Setup for Plone core development

IRC setup

You should consider getting a working IRC setup. A good part of the developer communication happens in real time in online chats in addition to the mailing lists and physical gatherings like sprints and conferences.

Details of setup and software can be found on the  Plone IRC chat page. Discussions happen in the #plone channel on freenode.net.

Dependencies

At any given time, the Plone community aims maintain two major releases of the Plone codebase. Currently, this includes Plone 3.x and Plone 4.x. Because the development community mostly uses zc.buildout (more on that later), the only upfront dependencies are the following:

  • A configured git client
  •  Download Python if you don't have it already (2.4 for Plone 3.x, 2.6 for Plone 4.x), and do ./configure; make; make install
  •  Download the Python Imaging Library (PIL) and once downloaded, do python setup.py install where "python" is the location of your Python 2.4 or 2.6 binary.

Getting the code

An in development version of Plone 3.x and 4.x can be easily retrieved and managed with zc.buildout recipes. A fantastic introduction to the topic of zc.buildout can be found in the  Managing projects with zc.buildout tutorial. Many Plone contributors have adopted this approach because it's easy to communicate a consistent setup process that tends to be reliable.

Setting up a Plone 3.x development instance is as easy as typing:

  • git clone -b 3.3  https://github.com/plone/buildout.coredev ./plone33devel
  • ... wait for a bunch of code to be checked out via Plone's GitHub repository ...
  • change directories into your buildout checkout with: cd ./plone33devel
  • python bootstrap.py (where "python" is your python 2.4 binary)
  • bin/buildout -v
  • start your new instance with ./bin/instance fg

Setting up a Plone 4.1 development instance is as easy as typing:

  • git clone -b 4.1  https://github.com/plone/buildout.coredev ./plone41devel
  • ... wait for a bunch of code to be checked out via Plone's GitHub repository ...
  • change directories into your buildout checkout with: cd ./plone41devel
  • python bootstrap.py (where "python" is your python 2.6 binary)
  • bin/buildout -v
  • start your new instance with ./bin/instance fg

Setting up a Plone 4.2 development instance is as easy as typing:

  • git clone -b 4.2  https://github.com/plone/buildout.coredev ./plone42devel
  • ... wait for a bunch of code to be checked out via Plone's GitHub repository ...
  • change directories into your buildout checkout with: cd ./plone42devel
  • python bootstrap.py (where "python" is your python 2.6 binary). For potential errors, see Buildout Errors Demystified.
  • bin/buildout -v
  • start your new instance with ./bin/instance fg

If at any point you want to switch between branches in the 4.X series, simply checkout the other branch and rerun buildout. If this is the first time you are getting the other branch:

git checkout -t origin/4.1

Subsequently you can omit the -t and just checkout the branch.

Running tests

The test command changed slightly from Plone 3 to Plone 4.

The short explanation is to choose a product or package you'd like to test, say "CMFPlone" and type the following from your buildout directory:

Plone 3
./bin/instance test -s Products.CMFPlone
Plone 4
./bin/test -s Products.CMFPlone

The full explanation for running and writing tests is of course in the excellent  Testing in Plone tutorial.

Updating your Buildout and Examining your Modifications

At any point in time, you can get the latest code for your chosen Plone development bundle by typing cd /path/to/buildout; git pull;

If you are making modifications to the Plone code, they are almost certainly being made to packages that makeup Plone. By navigating to the "src" directory at the root of your buildout, you can use your chosen git client to examine your modifications against the code repository.

Bug fixing

Packages currently under development can be found in your buildout's src directory. If the package you wish to make changes to is not there, run 

bin/develop checkout <name of package>
bin/develop rebuild

This will do a git clone of the package into your src directory and rerun the buildout so that it's recognized.

Note that all packages by default are checked out in read only mode. When you try to push to origin, it will likely give you an error that you need to update the url. The easiest way I know to do this is open up .git/config from the root of the package and change the url to exactly what it says to change it to. There is probably a better way but... who knows!

IMPORTANT

Once your changes have been made and committed, edit checkouts.cfg and add the name of the package to the auto-checkout list. This allows all other developers to use your updated package and alerts the package maintainers that the package needs a new release. It also tells jenkins to run all tests with your new package. If your like many of us, your fix will break something (on accident of course). Yay! So head on over to  https://jenkins.plone.org and make sure that everything runs smoothly.