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 consider the following guidelines.


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

* Before you submit a new issue, try asking for help first.

* If determined to create a new issue, first search Pelican
  Discussions and existing issues (open and closed) to see if your
  question has already been answered previously.


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 'plugins 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 "main"
  branch)

* 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) plugins, (3) settings files, and (4) "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 one of the above-listed elements (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 you can generate your site without problems using the steps above,
then your problem is unlikely to be caused by Pelican itself, and
therefore please consider reaching out to the maintainers of the
plugins/theme you are using instead of raising the topic with the
Pelican core community.

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. "python -m
  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 post your query as a new
thread in Pelican Discussions. Remember to include all the information
you prepared.


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 'plugins — you can ask for help  to make
that determination.

Also, if you intend to submit a pull request to address something for
which there is no existing issue, there is no need to create a new
issue and then immediately submit a pull request that closes it. You
can submit the pull request by itself.


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

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

* **Don't put multiple unrelated fixes/features in the same branch /
  pull request.** For example, if you're working 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. Similarly, any
  proposed changes to code style formatting should be in a completely
  separate pull request.

* Add a "RELEASE.md" file in the root of the project that contains the
  release type (major, minor, patch) and a summary of the changes that
  will be used as the release changelog entry. For example:

     Release type: minor

     Reload browser window upon changes to content, settings, or theme

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

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


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

* Adhere to the project's code style standards. See: Development
  Environment

* Ensure your code is compatible with the officially-supported Python
  releases.

* 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, the
following instructions will utilize Pip and PDM. These tools
facilitate managing virtual environments for separate Python projects
that are isolated from one another, so you can use different packages
(and package versions) for each.

Please note that Python >=3.9 is required for Pelican development.

*(Optional)* If you prefer to install PDM once for use with multiple
projects, you can install it via:

   curl -sSL https://pdm.fming.dev/install-pdm.py | python3 -

Point your web browser to the Pelican repository and tap the **Fork**
button at top-right. Then clone the source for your fork and add the
upstream project as a Git remote:

   mkdir ~/projects
   git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican
   cd ~/projects/pelican
   git remote add upstream https://github.com/getpelican/pelican.git

While PDM can dynamically create and manage virtual environments,
we're going to manually create and activate a virtual environment:

   mkdir ~/virtualenvs && cd ~/virtualenvs
   python3 -m venv pelican
   source ~/virtualenvs/pelican/*/activate

Install the needed dependencies and set up the project:

   python -m pip install invoke
   invoke setup

Your local environment should now be ready to go!


Development
===========

Once Pelican has been set up for local development, create a topic
branch for your bug fix or feature:

   git checkout -b name-of-your-bugfix-or-feature

Now you can make changes to Pelican, its documentation, and/or other
aspects of the project.


Setting up "git blame" (optional)
---------------------------------

"git blame" annotates lines in a file with information about the pull
request that last modified it. Sweeping shallow changes (like
formatting) can make that information less useful, so we keep a list
of such changes to be ignored. Run the following command to set this
up in your repository, adding "--global" if you want this setting to
apply to all repositories:

   git config blame.ignoreRevsFile .git-blame-ignore-revs

As noted in a useful article about "git blame", there are other
related settings you may find to be beneficial:

   # Add `?` to any lines that have had a commit skipped using --ignore-rev
   git config --global blame.markIgnoredLines true
   # Add `*` to any lines that were added in a skipped commit and can not be attributed
   git config --global blame.markUnblamableLines true


Running the test suite
----------------------

Each time you make changes to Pelican, there are two things to do
regarding tests: check that the existing tests pass, and add tests for
any new features or bug fixes. The tests are located in
"pelican/tests", and you can run them via:

   invoke tests

(For more on Invoke, see "invoke -l" to list tasks, or
https://pyinvoke.org for documentation.)

In addition to running the test suite, it is important to also ensure
that any lines you changed conform to code style guidelines. You can
check that via:

   invoke lint

If code style violations are found in lines you changed, correct those
lines and re-run the above lint command until they have all been
fixed. You do not need to address style violations, if any, for code
lines you did not touch.

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 command:

   invoke update-functional-tests

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.


Running a code coverage report
------------------------------

Code is more likely to stay robust if it is tested. Coverage is a
library that measures how much of the code is tested. To run it:

   invoke coverage

This will show overall coverage, coverage per file, and even line-by-
line coverage. There is also an HTML report available:

   open htmlcov/index.html


Building the docs
-----------------

If you make changes to the documentation, you should build and inspect
your changes before committing them:

   invoke docserve

Open http://localhost:8000 in your browser to review the
documentation. While the above task is running, any changes you make
and save to the documentation should automatically appear in the
browser, as it live-reloads when it detects changes to the
documentation source files.


Plugin development
------------------

To create a *new* Pelican plugin, please refer to the plugin template
repository for detailed instructions.

If you want to contribute to an *existing* Pelican plugin, follow the
steps above to set up Pelican for local development, and then create a
directory to store cloned plugin repositories:

   mkdir -p ~/projects/pelican-plugins

Assuming you wanted to contribute to the Simple Footnotes plugin, you
would first browse to the Simple Footnotes repository on GitHub and
tap the **Fork** button at top-right. Then clone the source for your
fork and add the upstream project as a Git remote:

   git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes
   cd ~/projects/pelican-plugins/simple-footnotes
   git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git

Install the needed dependencies and set up the project:

   invoke setup

Create a topic branch for your plugin bug fix or feature:

   git checkout -b name-of-your-bugfix-or-feature

After writing new tests for your plugin changes, run the plugin test
suite and check for code style compliance via:

   invoke tests
   invoke lint

If style violations are found, many of them can be addressed
automatically via:

   invoke format

If style violations are found even after running the above auto-
formatters, you will need to make additional manual changes until
"invoke lint" no longer reports any code style violations.


Submitting your changes
-----------------------

Assuming linting validation and tests pass, add a "RELEASE.md" file in
the root of the project that contains the release type (major, minor,
patch) and a summary of the changes that will be used as the release
changelog entry. For example:

   Release type: patch

   Fix browser reloading upon changes to content, settings, or theme

Commit your changes and push your topic branch:

   git add .
   git commit -m "Your detailed description of your changes"
   git push origin name-of-your-bugfix-or-feature

Finally, browse to your repository fork on GitHub and submit a pull
request.


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 the Pelican
logger will preprocess some arguments, such as exceptions.


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