Pelican
Docs » Contributing and feedback guidelines
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
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:
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-sitegit clone https​:​//​github​.​com​/​getpelican​/​pelican ~/projects/pelicanpelican 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:
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
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
Contribution quality standards
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 Poetry. 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.6+ is required for Pelican development.
(Optional) If you prefer to install Poetry once for use with multiple projects, you can install it via:
curl -sSL https​:​//​raw​.​githubusercontent​.​com​/​python​-​poetry​/​poetry​/​master​/​get​-​poetry​.​py | python -
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 ~/projectsgit clone https​:​//​github​.​com​/​YOUR_USERNAME​/​pelican​.​git ~/projects/pelicancd ~/projects/pelicangit remote add upstream https​:​//​github​.​com​/​getpelican​/​pelican​.​git
While Poetry can dynamically create and manage virtual environments, we’re going to manually create and activate a virtual environment:
mkdir ~/virtualenvs && cd ~/virtualenvspython3 -m venv pelicansource ~/​virtualenvs​/​pelican​/*/​activate
Install the needed dependencies and set up the project:
python -m pip install invokeinvoke setuppython -m pip install -e ~/projects/pelican
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.
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
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 bothen_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.
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 testsinvoke lint
If style violations are found, many of them can be addressed automatically via:
invoke blackinvoke isort
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: patchFix 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 fileimport logginglogger = logging​.​getLogger​(​__name__​)​# when neededlogger.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 missingWARNING: The resource best_cat_ever.jpg is missingWARNING: The resource cutest_cat.jpg is missingWARNING: The resource lolcat.jpg is missingWARNING: 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))
Next
Previous
Continuous Python Profiling Reduce End-User Latency & Infrastructure Costs Try Datadog for free
Ad by EthicalAds   ·   Monetize your site
© Copyright 2010 – present, Justin Mayer, Alexis Metaireau, and contributors Revision bb10d286.
Built with Sphinx using a theme provided by Read the Docs.
Pelican QuickstartInstalling PelicanWriting contentPublish your siteSettingsPluginsThemespelican-themesImporting an existing siteFrequently Asked Questions (FAQ)TipsFiling issuesHow to get helpThe #pelican IRC channelContributing codeUsing Git and GitHubContribution quality standardsSetting up the development environmentDevelopmentRunning the test suiteBuilding the docsPlugin developmentSubmitting your changesLogging tipsLimiting extraneous log messagesOutputting traceback in the logsPelican internalsSome history about PelicanRelease history
Pelican