diff options
Diffstat (limited to 'CONTRIBUTING.rst')
| -rw-r--r-- | CONTRIBUTING.rst | 67 |
1 files changed, 40 insertions, 27 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index fa314cd..cc756c8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,12 +3,14 @@ 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>`_ +* If your contribution is a new feature, you should make sure an issue exists + for it, and perhaps `discuss it <http://groups.google.com/group/nikola-discuss>`_ + on the mailing list. If you’re fixing a bug you just noticed, or are making a + minor change, creating an issue is optional, but please search for existing + issues. * **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 + you’re adding a new feature to foo the bars, do something like the following:: $ git checkout master @@ -26,38 +28,49 @@ Here are some guidelines about how you can contribute to Nikola: .. 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 + 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``. +* While working, rebase instead of merging (if possible). You can use rebase + instead of merge by default with ``git config pull.rebase true``. If rebases + fail, you can just use ``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 .`` +* **Add a CHANGELOG entry** at the *top* of ``CHANGES.txt`` mentioning issue number + and in the correct Features/Bugfixes section. Put it under *New in master*. + Create that section if it does not exist yet. Do not add an entry if the + change is trivial (documentation, typo fixes) or if the change is internal + (not noticeable to end users in any way). +* Add your name to ``AUTHORS.txt`` if the change is non-trivial. +* If you are fixing an issue, **include the issue number in commit** and/or pull + request text (eg. ``fix #1234``) so the issue `is automatically closed + <https://help.github.com/articles/closing-issues-via-commit-messages/>`_. +* Run ``flake8 nikola`` for **style consistency**. +* Ensure your Git name and e-mail are set correctly (they will be public) + and `added to GitHub <https://github.com/settings/emails>`_ * **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! + easily testable. +* **Test your code.** If you can, run the test suite with ``pytest tests/`` + (you will need to install pytest and some other requirements, see + ``requirements-tests.txt``). Alternatively, you can push and wait for Travis + to pick up and test your changes. -.. [1] Very inspired by `fabric's <https://github.com/fabric/fabric/blob/master/CONTRIBUTING.rst>`_ thanks! + If running tests is not feasible, please at least confirm that: -.. [2] For example, logging, or always making sure directories are created using ``utils.makedirs()`` + * the demo site (created with ``nikola init -qd demosite``) builds without errors + * the bugs you were trying to fix do not occur anymore (if applicable) + * the features you added work properly (if applicable) + +* 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()``. |