贡献和反馈指南

对Pelican的贡献有很多种方式。您可以改进文档，添加缺少的功能，并修复bug（或者只报告它们）。你也可以通过回顾和评论来帮助你 existing issues .

不要犹豫，叉Pelican和提交一个问题或拉在GitHub请求。进行此操作时，请考虑以下准则。

归档问题

  • 在提交问题之前，请尝试 asking for help 第一。

  • 如果确定要提交问题，请首先检查 existing issues ，包括已解决的问题。

如何获得帮助

在寻求帮助之前，请确保您已完成以下操作：

  1. 阅读 documentation 彻底地。如果您很匆忙，请至少使用上左上角提供的搜索字段 documentation 页。一定要阅读你正在使用的Pelican版本的文档。

  2. 使用搜索引擎（如DuckDuckGo、Google）搜索解决问题的方法。也许有人已经找到了一个解决方案，也许是 plugin 或特定的设置组合。

  3. 尝试在干净的环境中重现该问题，确保使用的是：

  • 最新发布的Pelican（或Pelican大师的最新Git克隆）

  • Pelican使用的最新版本库

  • 没有插件或只有那些与问题相关的插件

注： 最常见的问题来源是（1）主题、（2）设置文件和（3）中的异常 make/invoke 自动化包装器。如果在使用以下步骤生成站点时无法重现问题，那么问题几乎肯定与您选择的主题和/或设置文件有关（而不是Pelican本身）：

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

如果尽管做出了上述努力，您仍然无法解决您的问题，请务必在您的查询中包含以下信息，最好是以链接的形式上载到 paste service 、GitHub存储库或其他可公开访问的位置：

  • 描述您运行的鹈鹕版本（输出 pelican --version 或者是HEAD commit hash（如果您克隆了repo）以及如何准确地安装它（您使用的完整命令，例如。 python -m pip install pelican ）

  • 如果你正在寻找一种方法来获得一些最终结果，准备一份关于最终结果应该是什么样的详细描述（最好是以图像或模型页的形式），并详细解释到目前为止你为实现这个目标所做的工作。

  • 如果您试图解决某个问题，请准备一份关于如何重现问题的详细说明。如果这个问题不容易重现，开发者或志愿者就无法调试它。仅描述 最小步数 需要复制它（没有额外的插件等）。

  • 上载您的设置文件或任何其他自定义代码，这些代码将使人们能够重现问题，或查看您已尝试实现所需的最终结果。

  • 上传详细和 完成 输出日志和回溯（记住添加 --debug 旗帜： pelican --debug content [...] ）

一旦上述准备就绪，您可以通过（最好是）联系愿意提供帮助的人 #pelican IRC频道或发送消息到 authors at getpelican dot com . 记住把你准备的所有信息都包括进去。

PelicanIRC频道

  • 由于时区不同，您可能无法立即得到您的问题的答复，但请耐心等待并登录IRC-如果您等待足够长的时间（可能需要几个小时），就会有人回复您的问题。

  • 如果您手头没有IRC客户端，请使用 webchat.

  • 您可以使用此命令将IRC客户端定向到通道 IRC link 或者您可以手动加入 #pelican 上的IRC频道 freenode IRC network .

贡献代码

在你提交稿件之前，请先问一下你是否需要这样做，这样你就不会花很多时间去做那些因为已知原因而被拒绝的事情。你的新功能是否更适合你 plugin -你可以的 ask for help 做出这样的决定。

使用Git和GitHub

  • Create a new git branch 特定于您的更改（而不是在主分支中提交）。

  • Don't put multiple unrelated fixes/features in the same branch / pull request. 例如，如果您正在开发一个新功能，但发现了一个没有的错误修复程序 要求 你的新功能， 发出一个新的不同分支和拉请求 为了修复错误。

  • 添加 RELEASE.md 项目根目录下的文件，其中包含发布类型（主要、次要、修补程序）和将用作发布更改日志项的更改摘要。例如：

    Release type: minor

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

  • 通过 git diff --check 在提交之前。

  • 提交信息的第一行应该以现在时态动词开头，长度不超过50个字符，如果适用，还应包括相关的问题编号。 例子： Ensure proper PLUGIN_PATH behavior. Refs #428. 如果提交 完全修复 现有的错误报告，请使用 Fixes #585 或 Fix #585 语法（因此相关问题在PR merge时自动关闭）。

  • 在提交消息的第一行之后，添加一个空行，然后添加更详细的解释（如果相关）。

  • Squash your commits 以消除合并提交并确保提交历史记录干净易读。

  • 如果您以前提交过GitHub问题并希望提供解决该问题的代码， 请使用 hub pull-request 而不是使用GitHub的webui提交请求。这不是一个绝对的要求，但是可以让维护人员的生活更轻松！明确地： install hub 然后运行 hub pull-request -i [ISSUE] 将GitHub问题转换为包含代码的pull请求。

  • 发出请求后，持续集成（CI）系统将为所有受支持的Python版本运行测试套件，并检查PEP8的遵从性。如果这些检查中有任何一个失败，你应该修复它们。（如果CI系统上的测试失败，但似乎在本地通过，请确保本地测试运行不会跳过任何测试。）

稿件质量标准

  • 坚持 PEP8 coding standards . 这可以通过 pycodestyle 或 flake8 工具，特别是后者将为您提供一些有用的提示，说明如何改进代码/格式。我们尝试将行长度保持在PEP8指定的最大79个字符以内。因为这有时会影响可读性，所以硬/强制最大值为88个字符。

  • 确保您的代码与 officially-supported Python releases .

  • 添加文档和测试的更改。未记录和未测试的功能将不被接受。

  • Run all the tests 在Pelican支持的所有Python版本上 以确保没有意外损坏。

看看我们的 Git Tips 页面或 ask for help 如果您需要帮助或对这些指南有任何疑问。

建立发展环境

虽然有许多方法可以设置开发环境，但下面的说明将利用 Pip 和 Poetry. 这些工具有助于管理彼此独立的Python项目的虚拟环境，因此您可以为每个项目使用不同的包（和包版本）。

请注意，Pelican开发需要Python3.6+。

（可选） 如果您希望一次安装诗歌以用于多个项目，可以通过以下方式安装：

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

将web浏览器指向 Pelican repository 点击 Fork 右上角的按钮。然后克隆fork的源代码并将上游项目添加为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

poether可以动态地创建和管理虚拟环境，我们将手动创建和激活一个虚拟环境：

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

安装所需的依赖项并设置项目：

python -m pip install invoke
invoke setup
python -m pip install -e ~/projects/pelican

你的当地环境现在应该准备好了！

开发

一旦Pelican被设置为本地开发，为您的bug修复或特性创建一个主题分支：

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

现在您可以对Pelican、其文档和/或项目的其他方面进行更改。

运行测试套件

每次对Pelican进行更改时，关于测试有两件事要做：检查现有的测试是否通过，以及添加测试以确定是否有新特性或bug修复。测试位于 pelican/tests ，您可以通过：

invoke tests

除了运行测试套件外，还必须确保更改的任何行都符合代码样式准则。你可以通过：

invoke lint

如果在您更改的行中发现代码样式冲突，请更正这些行并重新运行上面的lint命令，直到它们全部修复为止。对于未触及的代码行，不需要解决样式冲突（如果有）。

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

您还可能会发现有些测试被跳过，因为某些依赖项（例如Pandoc）没有安装。这并不自动意味着这些测试已经通过；您至少应该验证任何跳过的测试都不会受到更改的影响。

您应该在每个受支持的Python版本下运行测试套件。最好是为每个版本创建一个单独的Python环境。 Tox 是一个有用的工具，可以自动运行内部的测试 virtualenv 环境。

构建文档

如果对文档进行更改，则应在提交更改之前生成并检查更改：

invoke docserve

打开http://localhost：8000在浏览器中查看文档。当上面的任务正在运行时，您对文档所做的任何更改和保存都应该自动出现在浏览器中，因为它会在检测到文档源文件的更改时实时重新加载。

插件开发

创建一个 new Pelican插件，请参考 plugin template 详细说明的存储库。

如果你想为 现有的 Pelican plugin，按照上面的步骤为本地开发设置Pelican，然后创建一个目录来存储克隆的插件库：

mkdir -p ~/projects/pelican-plugins

假设您想对SimpleFootnotes插件有所贡献，那么首先浏览 Simple Footnotes GitHub上的存储库并点击 Fork 右上角的按钮。然后克隆fork的源代码并将上游项目添加为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

安装所需的依赖项并设置项目：

invoke setup

为插件错误修复或功能创建主题分支：

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

为插件更改编写新测试后，运行插件测试套件并通过以下方式检查代码样式符合性：

invoke tests
invoke lint

如果发现样式冲突，可以通过以下方式自动解决：

invoke black
invoke isort

如果在运行上述自动格式化程序后仍发现样式冲突，则需要进行额外的手动更改，直到 invoke lint 不再报告任何代码样式冲突。

提交您的更改

假设linting验证和测试通过，添加一个 RELEASE.md 项目根目录下的文件，其中包含发布类型（主要、次要、修补程序）和将用作发布更改日志项的更改摘要。例如：

Release type: patch

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

提交更改并推送主题分支：

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

最后，浏览到GitHub上的存储库fork并提交一个pull请求。

日志记录提示

尝试使用适当级别的日志记录。

对于记录不重复的消息，请使用通常的Python方法：

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

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

不要自己格式化日志消息。使用 %s 格式化消息并将参数传递给记录器。这很重要，因为Pelican记录器将预处理一些参数，例如异常。

限制无关的日志消息

如果日志消息可能多次出现，您可能需要限制日志以防止泛滥。为此，请使用 extra 日志记录消息的关键字参数，格式如下：

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

或者，也可以设置 'limit_args' 作为 extra 判断您的通用消息是否需要格式化。

限制设置为 5 ，即前四个日志 'limit_msg' 正常输出，但第五个将使用 'limit_msg' （和 'limit_args' 如果有）。第五次之后，相应的日志消息将被忽略。

例如，如果要记录丢失的资源，请使用以下代码：

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

日志消息将显示如下：

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

在日志中输出回溯

如果你在一个 except 块，您可能还需要提供回溯信息。你可以通过设置 exc_info 关键字参数 True 记录期间。但是，在默认情况下这样做是不可取的，因为回溯很长，并且可能会让普通用户感到困惑。尽量把他们限制在 --debug 模式如下：

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