1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
Patch submission guidelines [1]_
--------------------------------
Here are some guidelines about how you can contribute to Nikola:
* First, make sure there is an open issue for your change. Perhaps,
if it's a new feature, you probably want to
`discuss it first <http://groups.google.com/group/nikola-discuss>`_
* **Create a new Git branch specific to your change(s).** For example, if
you're adding a new feature to foo the bars, do something like the
following::
$ git checkout master
$ git pull
$ git checkout -b foo-the-bars
<hack hack hack>
$ git push origin HEAD
<submit pull request based on your new 'foo-the-bars' branch>
This makes life much easier for maintainers if you have (or ever plan to
have) additional changes in your own ``master`` branch.
Also, if you have commit rights to the main Nikola repository, we suggest
having your branch there, instead of a personal fork.
.. admonition:: A corollary:
Please **don't put multiple fixes/features in the same
branch/pull request**! In other words, if you're hacking on new feature X
and find a bugfix that doesn't *require* new feature X, **make a new
distinct branch and PR** for the bugfix.
* You may want to use the `Tim Pope’s Git commit messages standard
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
It’s not necessary, but if you are doing something big, we recommend
describing it in the commit message.
* While working, **rebase instead of merging** (if possible). We encourage
using ``git rebase`` instead of ``git merge``. If you are using
``git pull``, please run ``git config pull.rebase true`` to prevent merges
from happening and replace them with rebase goodness. There is also an
“emergency switch” in case rebases fail and you do not know what to do:
``git pull --no-rebase``.
* **Make sure documentation is updated** — at the very least, keep docstrings
current, and if necessary, update the reStructuredText documentation in ``docs/``.
* **Add a changelog entry** at the top of ``CHANGES.txt`` mentioning issue number
and in the correct Features/Bugfixes section. (while creating the new
changelog entry, put it in the version that does not exist (consult
setup.py) or create a new section)
* **Run flake8** for style consistency. Use ``flake8 --ignore=E501 .``
* **Try writing some tests** if possible — again, following existing tests is
often easiest, and a good way to tell whether the feature you are modifying is
easily testable. You will find instructions in ``tests/README.rst``.
(alternatively you can push and wait for Travis to pick up and test your changes,
but we encourage to run them locally before pushing.)
* Make sure to mention the issue it affects in the description of your pull request,
so it's clear what to test and how to do it.
* There are some quirks to how Nikola's codebase is structured, and to how
some things need to be done [2]_ but don't worry, we'll guide you!
.. [1] Very inspired by `fabric's <https://github.com/fabric/fabric/blob/master/CONTRIBUTING.rst>`_ thanks!
.. [2] For example, logging, or always making sure directories are created using ``utils.makedirs()``
|
