GitHub-only

WARNING: If you are reading this on GitHub, DON’T! Read the documentation at docs.plone.org so you have working references and proper formatting.

Development environment

This section is meant for contributors to the plone.api project. Its purpose is to guide them through the steps needed to start contributing.

Locations of information and tools

Prerequisites

System libraries

First let’s look at ‘system’ libraries and applications that are normally installed with your OS packet manager, such as apt, aptitude, yum, etc.:

  • libxml2 - An xml parser written in C.

  • libxslt - XSLT library written in C.

  • git - Version control system.

  • gcc - The GNU Compiler Collection.

  • g++ - The C++ extensions for gcc.

  • GNU make - The fundamental build-control tool.

  • GNU tar - The (un)archiving tool for extracting downloaded archives.

  • bzip2 and gzip decompression packages - gzip is nearly standard, however some platforms will require that bzip2 be installed.

  • Python 2.7 - Linux distributions normally already have it, OS X users should use https://github.com/collective/buildout.python to get a clean Python version (the one that comes with OS X is broken).

Python tools

Todo

Update this description:

  • add tox and propably pip.

  • easy_install should be removed.

  • question if virtualenv should be used, as tox also replaces this step.

Then you’ll also need to install some Python specific tools:

  • easy_install - the Python packaging system (download http://peak.telecommunity.com/dist/ez_setup.py and run sudo python2.7 ez_setup.py.

  • virtualenv - a tool that assists in creating isolated Python working environments. Run sudo easy_install virtualenv after your have installed easy_install above.

Note

Again, OS X users should use https://github.com/collective/buildout.python, it will make your life much easier to have a cleanly compiled Python instead of using the system one that is broken in many deeply confusing ways.

Further information

If you experience problems read through the following links as almost all of the above steps are required for a default Plone development environment:

If you are an OS X user, you first need a working Python implementation (the one that comes with the operating system is broken). Use https://github.com/collective/buildout.python and be happy. Also applicable to other OSes, if getting a working Python proves a challenge.

Git workflow & branching model

Our repository on GitHub has the following layout:

  • feature branches: all development for new features must be done in dedicated branches, normally one branch per feature,

  • master branch: when features get completed they are merged into the master branch; bugfixes are commited directly on the master branch,

  • tags: whenever we create a new release we tag the repository so we can later re-trace our steps, re-release versions, etc.

Squashing commits

In order to keep a clear and concise git history, it is good practice to squash commits before merging. Use git rebase --interactive to squash all commits that you think are unnecessary.

Creating and using the development environment

Todo

Update this section as it seams out of date, there is no Makefile so this description makes no sense anymore.

Go to your projects folder and download the lastest plone.api code:

[you@local ~]$ cd <your_work_folder>
[you@local work]$ git clone https://github.com/plone/plone.api.git

Now cd into the newly created directory and build your environment:

[you@local work]$ cd plone.api
[you@local plone.api]$ make

Go make some tea while

  • make creates an isolated Python environment in your plone.api` folder,

  • bootstraps zc.buildout,

  • fetches all dependencies,

  • builds Plone,

  • runs all tests and

  • generates documentation so you can open it locally later on.

Other commands that you may want to run:

[you@local plone.api]$ make tests  # run all tests and syntax validation
[you@local plone.api]$ make docs   # re-generate documentation
[you@local plone.api]$ make clean  # reset your env back to a fresh start
[you@local plone.api]$ make        # re-build env, generate docs, run tests

Open Makefile in your favorite code editor to see all possible commands and what they do. And read http://www.gnu.org/software/make/manual/make.html to learn more about make.

Working on an issue

Our GitHub account contains a list of open issues. Click on one that catches your attention. If the issue description says No one is assigned it means no-one is already working on it and you can claim it as your own. Click on the button next to the text and make yourself the one assigned for this issue.

Based on our Git workflow & branching model all new features must be developed in separate git branches. So if you are not doing a very trivial fix, but rather adding new features/enhancements, you should create a feature branch. This way your work is kept in an isolated place where you can receive feedback on it, improve it, etc. Once we are happy with your implementation, your branch gets merged into master at which point everyone else starts using your code.

[you@local plone.api]$ git checkout master  # go to master branch
[you@local plone.api]$ git checkout -b issue_17  # create a feature branch
# replace 17 with the issue number you are working on

# change code here

[you@local plone.api]$ git add -p && git commit  # commit my changes
[you@local plone.api]$ git push origin issue_17  # push my branch to GitHub
# at this point others can see your changes but they don't get effected by
them; in other words, others can comment on your code without your code
changing their development environments

Read more about Git branching at http://learn.github.com/p/branching.html and on our Git workflow at Working with Git and GitHub.

Once you are done with your work and you would like us to merge your changes into master, go to GitHub to do a pull request. Open a browser and point it to https://github.com/plone/plone.api/tree/issue_<ISSUE_NUMBER>. There you should see a Pull Request button. Click on it, write some text about what you did and anything else you would like to tell the one who will review your work, and finally click Send pull request. Now wait that someone comes by and merges your branch (don’t do it yourself, even if you have permissions to do so).

An example pull request text:

Please merge my branch that resolves issue #13,
where I added the get_navigation_root() method.

Commit checklist

Before every commit you should:

  • Run unit tests and syntax validation checks.

  • Add an entry to changes (if applicable).

  • Add/modify sphinx-docs (if applicable).

All syntax checks and all tests can be run with a single command. This command also re-generates your documentation.

$ make

Note

It pays off to invest a little time to make your editor run pep8 and pyflakes on a file every time you save that file (or use flake8 which combines both). This saves you lots of time in the long run.

Travis Continuous Integration

On every push to GitHub, Travis runs all tests and syntax validation checks and reports build outcome to the #sprint IRC channel and the person who committed the last change.

Travis is configured with the .travis.yml file located in the root of this package.

Sphinx Documentation

Un-documented code is broken code.

For every feature you add to the codebase you should also add documentation for it to docs/.

After adding/modifying documentation, run make to re-generate your docs.

Publicly available documentation on http://api.plone.org is automatically generated from these source files, periodically. So when you push changes to master on GitHub you should soon be able to see them published on api.plone.org.

Read the reStructuredText Primer to brush up on your reST skills.

Example:

def add(a, b):
    """Calculate the sum of the two parameters.

    Also see the :func:`mod.path.my_func`, :meth:`mod.path.MyClass.method` and :attr:`mod.path.MY_CONSTANT` for more details.

    :param a: The first operand.
    :type a: :class:`mod.path.A`

    :param b: The second operand.
    :type b: :class:`mod.path.B`

    :rtype: int
    :return: The sum of the operands.
    :raises: `KeyError`, if the operands are not the correct type.
    """

Attributes are documented using the #: marker above the attribute. The documentation may span multiple lines.

#: Description of the constant value
MY_CONSTANT = 0xc0ffee

class Foobar(object):

    #: Description of the class variable which spans over
    #: multiple lines
    FOO = 1