Contributing and feedback guidelines
************************************

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 an issue or pull request on
GitHub. When doing so, please adhere to the following guidelines.


Filing issues
=============

* Before you file an issue, try asking for help first.

* If determined to file an issue, first check for existing issues,
  including closed issues.


How to get help
===============

Before you ask for help, please make sure you do the following:

1. Read the documentation thoroughly. If in a hurry, at least use
   the search field that is provided at top-left on the documentation
   pages. Make sure you read the docs for the Pelican version you are
   using.

2. Use a search engine (e.g., DuckDuckGo, Google) to search for a
   solution to your problem. Someone may have already found a
   solution, perhaps in the form of a plugin or a specific combination
   of settings.

3. Try reproducing the issue in a clean environment, ensuring you
   are using:

* latest Pelican release (or an up-to-date git clone of Pelican
  master)

* latest releases of libraries used by Pelican

* no plugins or only those related to the issue

**NOTE:** The most common sources of problems are anomalies in (1)
themes, (2) settings files, and (3) "make"/"invoke" automation
wrappers. If you can't reproduce your problem when using the following
steps to generate your site, then the problem is almost certainly with
your chosen theme and/or settings file (and not Pelican itself):

   cd ~/projects/your-site
   git clone https://github.com/getpelican/pelican ~/projects/pelican
   pelican content -s ~/projects/pelican/samples/pelican.conf.py -t ~/projects/pelican/pelican/themes/notmyidea

If despite the above efforts you still cannot resolve your problem, be
sure to include in your inquiry the following information, preferably
in the form of links to content uploaded to a paste service, GitHub
repository, or other publicly-accessible location:

* Describe what version of Pelican you are running (output of
  "pelican --version" or the HEAD commit hash if you cloned the repo)
  and how exactly you installed it (the full command you used, e.g.
  "pip install pelican").

* If you are looking for a way to get some end result, prepare a
  detailed description of what the end result should look like
  (preferably in the form of an image or a mock-up page) and explain
  in detail what you have done so far to achieve it.

* If you are trying to solve some issue, prepare a detailed
  description of how to reproduce the problem. If the issue cannot be
  easily reproduced, it cannot be debugged by developers or
  volunteers. Describe only the **minimum steps** necessary to
  reproduce it (no extra plugins, etc.).

* Upload your settings file or any other custom code that would
  enable people to reproduce the problem or to see what you have
  already tried to achieve the desired end result.

* Upload detailed and **complete** output logs and backtraces
  (remember to add the "--debug" flag: "pelican --debug content
  [...]")

Once the above preparation is ready, you can contact people willing to
help via (preferably) the "#pelican" IRC channel or send a message to
"authors at getpelican dot com". Remember to include all the
information you prepared.


The #pelican IRC channel
------------------------

* Because of differing time zones, you may not get an immediate
  response to your question, but please be patient and stay logged
  into IRC — someone will almost always respond if you wait long
  enough (it may take a few hours).

* If you don't have an IRC client handy, use the webchat for quick
  feedback.

* You can direct your IRC client to the channel using this IRC link
  or you can manually join the "#pelican" IRC channel on the freenode
  IRC network.


Contributing code
=================

Before you submit a contribution, please ask whether it is desired so
that you don't spend a lot of time working on something that would be
rejected for a known reason. Consider also whether your new feature
might be better suited as a plugin — you can ask for help  to make
that determination.


Using Git and GitHub
--------------------

* Create a new git branch specific to your change (as opposed to
  making your commits in the master branch).

* **Don't put multiple unrelated 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.

* Check for unnecessary whitespace via "git diff --check" before
  committing.

* 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).

* Squash your commits to eliminate merge commits and ensure a clean
  and readable commit history.

* 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.

* After you have issued a pull request, Travis will run the test
  suite for all supported Python versions and check for PEP8
  compliance. If any of these checks fail, you should fix them. (If
  tests fail on Travis but seem to pass locally, ensure that local
  test runs aren't skipping any tests.)


Contribution quality standards
------------------------------

* Adhere to PEP8 coding standards. This can be eased via the
  pycodestyle 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. If you are relying on your editor for PEP8
  compliance, note that the line length specified by PEP8 is 79
  (excluding the line break).

* Ensure your code is compatible with the latest Python 2.7 and 3.x
  releases — see our compatibility cheatsheet for more details.

* Add docs and tests for your changes. Undocumented and untested
  features will not be accepted.

* Run all the tests **on all versions of Python supported by
  Pelican** to ensure nothing was accidentally broken.

Check out our Git Tips page or ask for help 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, we
recommend using Virtualenv. This tool allows you to set up separate
environments for separate Python projects that are isolated from one
another so you can use different packages (and package versions) for
each.

If you don't have "virtualenv" installed, you can install it via:

   $ pip install virtualenv

Use "virtualenv" to create and activate a virtual environment:

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

Clone the Pelican source into a subfolder called "src/pelican":

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

Install the development dependencies:

   $ pip install -r requirements/developer.pip

Install Pelican and its dependencies:

   $ python setup.py develop

Or using "pip":

   $ pip install -e .

To conveniently test on multiple Python versions, we also provide a
".tox" file.


Building the docs
=================

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

   $ pip install -r requirements/docs.pip
   $ cd 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 -Wd -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,
**make sure you have both** "en_EN.utf8" **and** "fr_FR.utf8"
**locales installed**, and then run the following two commands:

   $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
       -s samples/pelican.conf.py samples/content/
   $ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
       -s samples/pelican.conf_FR.py samples/content/
   $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
       samples/content/

You may also find that some tests are skipped because some dependency
(e.g., Pandoc) is not installed. This does not automatically mean that
these tests have passed; you should at least verify that any skipped
tests are not affected by your changes.

You should run the test suite under each of the supported versions of
Python. This is best done by creating a separate Python environment
for each version. Tox is a useful tool to automate running tests
inside "virtualenv" environments.


Python 2/3 compatibility development tips
=========================================

Here are some tips that may be useful for writing code that is
compatible with both Python 2.7 and Python 3:

* Use new syntax. For example:

  * "print .. -> print(..)"

  * "except .., e -> except .. as e"

* Use new methods. For example:

  * "dict.iteritems() -> dict.items()"

  * "xrange(..) - > list(range(..))"

* Use "six" where necessary. For example:

  * "isinstance(.., basestring) -> isinstance(.., six.string_types)"

  * "isinstance(.., unicode) -> isinstance(.., six.text_type)"

* Assume every string and literal is Unicode:

  * Use "from __future__ import unicode_literals"

  * Do not use the prefix "u'" before strings.

  * Do not encode/decode strings in the middle of something. Follow
    the code to the source/target of a string and encode/decode at the
    first/last possible point.

  * In particular, write your functions to expect and to return
    Unicode.

  * Encode/decode strings if the string is the output of a Python
    function that is known to handle this badly. For example,
    "strftime()" in Python 2.

  * Do not use the magic method "__unicode()__" in new classes. Use
    only "__str()__" and decorate the class with
    "@python_2_unicode_compatible".

* "setlocale()" in Python 2 fails 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, enclose
  the locale name with "str()"; in Python 2 this casts the name to a
  byte string, while in Python 3 this should do nothing, because the
  locale name was already Unicode.

* Do not start integer literals with a zero. This is a syntax error
  in Python 3.

* Unfortunately there seems to be no octal notation that is valid in
  both Python 2 and 3. Use decimal notation instead.


Logging tips
============

Try to use logging with appropriate levels.

For logging messages that are not repeated, use the usual Python way:

   # at top of file
   import logging
   logger = logging.getLogger(__name__)

   # when needed
   logger.warning("A warning with %s formatting", arg_to_be_formatted)

Do not format log messages yourself. Use "%s" formatting in messages
and pass arguments to logger. This is important, because Pelican
logger will preprocess some arguments (like Exceptions) for Py2/Py3
compatibility.


Limiting extraneous log messages
--------------------------------

If the log message can occur several times, you may want to limit the
log to prevent flooding. In order to do that, use the "extra" keyword
argument for the logging message in the following format:

   logger.warning("A warning with %s formatting", arg_to_be_formatted,
       extra={'limit_msg': 'A generic message for too many warnings'})

Optionally, you can also set "'limit_args'" as a tuple of arguments in
"extra" dict if your generic message needs formatting.

Limit is set to "5", i.e, first four logs with the same "'limit_msg'"
are outputted normally but the fifth one will be logged using
"'limit_msg'" (and "'limit_args'" if present). After the fifth,
corresponding log messages will be ignored.

For example, if you want to log missing resources, use the following
code:

   for resource in resources:
       if resource.is_missing:
           logger.warning(
               'The resource %s is missing', resource.name,
               extra={'limit_msg': 'Other resources were missing'})

The log messages will be displayed as follows:

   WARNING: The resource prettiest_cat.jpg is missing
   WARNING: The resource best_cat_ever.jpg is missing
   WARNING: The resource cutest_cat.jpg is missing
   WARNING: The resource lolcat.jpg is missing
   WARNING: Other resources were missing


Outputting traceback in the logs
--------------------------------

If you're logging inside an "except" block, you may want to provide
the traceback information as well. You can do that by setting
"exc_info" keyword argument to "True" during logging. However, doing
so by default can be undesired because tracebacks are long and can be
confusing to regular users. Try to limit them to "--debug" mode like
the following:

   try:
       some_action()
   except Exception as e:
       logger.error('Exception occurred: %s', e,
           exc_info=settings.get('DEBUG', False))
