How to contribute

There are many ways to contribute to Pelican. You can improve the documentation, add missing features, and fix bugs (or just report them). You can also help out by reviewing and commenting on existing issues.

Don’t hesitate to fork Pelican and submit a pull request on GitHub. When doing so, please adhere to the following guidelines.

Contribution submission guidelines

• Consider whether your new feature might be better suited as a plugin. Folks are usually available in the #pelican IRC channel if help is needed to make that determination.
• Create a new git branch specific to your change (as opposed to making your commits in the master branch).
• Don’t put multiple fixes/features in the same branch / pull request. For example, if you’re hacking on a new feature and find a bugfix that doesn’t require your new feature, make a new distinct branch and pull request for the bugfix.
• Adhere to PEP8 coding standards whenever possible.
• Check for unnecessary whitespace via git diff --check before committing.
• Add docs and tests for your changes.
• Run all the tests on both Python 2.7+ and 3.2+ to ensure nothing was accidentally broken.
• First line of your commit message should start with present-tense verb, be 50 characters or less, and include the relevant issue number(s) if applicable. Example: Ensure proper PLUGIN_PATH behavior. Refs #428. If the commit completely fixes an existing bug report, please use Fixes #585 or Fix #585 syntax (so the relevant issue is automatically closed upon PR merge).
• After the first line of the commit message, add a blank line and then a more detailed explanation (when relevant).
• If you have previously filed a GitHub issue and want to contribute code that addresses that issue, please use hub pull-request instead of using GitHub’s web UI to submit the pull request. This isn’t an absolute requirement, but makes the maintainers’ lives much easier! Specifically: install hub and then run hub pull-request to turn your GitHub issue into a pull request containing your code.

Check out our Git Tips page or ask on the #pelican IRC channel if you need assistance or have any questions about these guidelines.

Setting up the development environment

While there are many ways to set up one’s development environment, following is a method that uses virtualenv. If you don’t have virtualenv installed, you can install it via:

$ pip install virtualenv

Virtual environments allow you to work on Python projects which are isolated from one another so you can use different packages (and package versions) with different projects.

To create and activate a virtual environment, use the following syntax:

$ virtualenv ~/virtualenvs/pelican
$ cd ~/virtualenvs/pelican
$ . bin/activate

To clone the Pelican source:

$ git clone https://github.com/getpelican/pelican.git src/pelican

To install the development dependencies:

$ cd src/pelican
$ pip install -r dev_requirements.txt

To install Pelican and its dependencies:

$ python setup.py develop

Coding standards

Try to respect what is described in the PEP8 specification when making contributions. This can be eased via the pep8 or flake8 tools, the latter of which in particular will give you some useful hints about ways in which the code/formatting can be improved.

Building the docs

If you make changes to the documentation, you should preview your changes before committing them:

$ pip install sphinx
$ cd src/pelican/docs
$ make html

Open _build/html/index.html in your browser to preview the documentation.

Running the test suite

Each time you add a feature, there are two things to do regarding tests: check that the existing tests pass, and add tests for the new feature or bugfix.

The tests live in pelican/tests and you can run them using the “discover” feature of unittest:

$ python -m unittest discover

After making your changes and running the tests, you may see a test failure mentioning that “some generated files differ from the expected functional tests output.” If you have made changes that affect the HTML output generated by Pelican, and the changes to that output are expected and deemed correct given the nature of your changes, then you should update the output used by the functional tests. To do so, you can use the following two commands:

$ pelican -o pelican/tests/output/custom/ -s samples/pelican.conf.py \
    samples/content/
$ pelican -o pelican/tests/output/basic/ samples/content/

Testing on Python 3.x

Testing on Python 3.x currently requires some extra steps: installing Python 3.x-compatible versions of dependent packages and plugins.

However, you must tell tox to use those Python 3.x-compatible libraries. If you forget this, tox will pull the regular packages from PyPI, and the tests will fail.

Tell tox about the local packages thusly: enter the source directory of smartypants and run tox there. Do this again for the typogrify and webassets packages. SmartyPants and Typogrify do not have real tests, and webassets will fail noisily, but as a result we get these libraries neatly packaged in tox’s distshare directory, which we need in order to run tox for Pelican.

Python 3.x development tips

Here are some tips that may be useful when doing some code for both Python 2.7 and Python 3.x at the same time:

• Assume every string and literal is unicode (import unicode_literals):
  • Do not use prefix u'.
  • Do not encode/decode strings in the middle of sth. Follow the code to the source (or target) of a string and encode/decode at the first/last possible point.
  • In other words, write your functions to expect and to return unicode.
  • Encode/decode strings if e.g. the source is a Python function that is known to handle this badly, e.g. strftime() in Python 2.
• Use new syntax: print function, “except ... as e” (not comma) etc.
• Refactor method calls like dict.iteritems(), xrange() etc. in a way that runs without code change in both Python versions.
• Do not use magic method __unicode()__ in new classes. Use only __str()__ and decorate the class with @python_2_unicode_compatible.
• Do not start int literals with a zero. This is a syntax error in Py3k.
• Unfortunately I did not find an octal notation that is valid in both Pythons. Use decimal instead.
• use six, e.g.:
  • isinstance(.., basestring) -> isinstance(.., six.string_types)
  • isinstance(.., unicode) -> isinstance(.., six.text_type)
• setlocale() in Python 2 bails when we give the locale name as unicode, and since we are using from __future__ import unicode_literals, we do that everywhere! As a workaround, I enclosed the localename with str(); in Python 2 this casts the name to a byte string, in Python 3 this should do nothing, because the locale name already had been unicode.
• Kept range() almost everywhere as-is (2to3 suggests list(range())), just changed it where I felt necessary.
• Changed xrange() back to range(), so it is valid in both Python versions.