diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..310f79b3 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,37 @@ +Contribution submission guidelines +================================== + +* Consider whether your new feature might be better suited as a + :doc:`plugin`. Folks are usually available in the + `#pelican IRC channel`_ to help 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 two returns and then a more + detailed explanation (when relevant). +* **Use** ``hub pull-request`` when submitting code for a **pre-existing GitHub + Issue**. This isn't an absolute requirement, but makes the maintainers' lives + much easier! Specifically: `install hub + `_ and then run `hub + pull-request `_ to turn the + 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. + +.. _`#pelican IRC channel`: http://webchat.freenode.net/?channels=pelican&uio=d4 +.. _`Create a new git branch`: https://github.com/getpelican/pelican/wiki/Git-Tips#making-your-changes +.. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips diff --git a/docs/contribute.rst b/docs/contribute.rst index e53fabf5..b50532bd 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -1,29 +1,34 @@ -How to contribute? -################### -There are many ways to contribute to Pelican. You can enhance the -documentation, add missing features, and fix bugs (or just report them). +How to contribute +################# -Don't hesitate to fork and make a pull request on GitHub. When doing so, please -create a new feature branch as opposed to making your commits in the master -branch. +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. + +.. include:: ../CONTRIBUTING.rst Setting up the development environment ====================================== -You're free to set up your development environment any way you like. Here is a -way using the `virtualenv `_ and `virtualenvwrapper -`_ tools. If you don't -have them, you can install these both of these packages via:: +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 virtualenvwrapper + $ 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 a virtual environment, use the following syntax:: +To create and activate a virtual environment, use the following syntax:: - $ mkvirtualenv pelican + $ virtualenv pelican ~/virtualenvs/pelican + $ cd ~/virtualenvs/pelican + $ . bin/activate To clone the Pelican source:: @@ -38,59 +43,76 @@ 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: -checking that the existing tests pass, and adding tests for the new feature +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 unittest2:: +The tests live in ``pelican/tests`` and you can run them using the +"discover" feature of ``unittest``:: - $ unit2 discover + $ python -m unittest discover -If you have made changes that affect the output of a Pelican-generated weblog, -then you should update the output used by functional tests. -To do so, you can use the following two commands:: +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 for python3 -------------------- +Testing on Python 3.x +--------------------- -On Python 3, if you have installed the Py3k compatible versions of the -plugins manual testing with ``unit2 discover`` is also straightforward. +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 Py3k libraries. If you forget this, -tox will pull the regular packages from PyPi and the tests will fail. +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 typogrify and webassets. -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. And this we need to run tox for Pelican. +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. -Coding standards -================ +Python 3.x development tips +=========================== -Try to respect what is described in the `PEP8 specification -`_ when providing patches. 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. +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: -Python3 support -=============== +- Assume every string and literal is unicode (import unicode_literals): -Here are some tips that may be useful when doing some code for both python2 and -python3 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