项目贡献与意见反馈¶

有很多渠道可以参与到贡献项目中来，例如帮助改进文档、添加缺失的特性、修复与报告bug。可以从查看已有 issues 开始。

随时随地都可以fork Pelican或是在GitHub上提交issue或PR。

提出issue¶

在你提交一个新的issue之前，可以先尝试请求他人帮助。
当你决定要提出新的issue时，先在 Pelican的讨论版和已有issues 中搜索一下，（开放关闭的issue都搜一下），来看看你的问题是不是有人之前已经提出过。

如何获取帮助¶

在寻求帮助之前，请先尝试如下步骤：

完整阅读 documentation 。如果你很急，至少先在 documentation 左上角的搜索栏中尝试搜索。确保你阅读的文档和使用的Pelican版本相匹配。
使用搜索引擎（例如 DuckDuckGo、Google）搜索遇到问题的解决方案。互联网上可能已经有人遇到过相同的问题，解决方法可能包括使用某些 plugins 或配置一系列的设置选项。
尝试在一个尽可能简单的环境中重现问题，并确保以下几点：

使用最新版本的Pelican（或是用Git克隆Pelican的main分支）
将Pelican使用的库升级到最新版本
此环境中没有使用插件或是只使用和问题相关的插件

注意： 最常见的问题基本上都产生于主题、插件、设置文件和自动化工具 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

如果按照上述步骤能够正常生成站点，那么你的问题不太可能是由Pelican本身导致的，请考虑联系对应插件/主题的维护者，而不是在Pelican内核的社区中提出问题。

经过上面这些努力，若您仍无法解决问题，确保你的提问中包括如下信息，可以以 paste service 链接、GitHub仓库，或者其他可公开获取的形式提供：

描述正在运行的Pelican版本信息（可以通过 pelican --version 命令得到，如果clone的源仓库则可以查看HEAD commit的哈希值），以及你是如何安装Pelican的（要包括使用到的命令，例如 python -m pip install pelican）
如果你希望产生某种特定的最终结果，请详细描述此最终结果是什么样的（最好以图片或者伪页面的形式），，并且细致讲述你做了哪些尝试。
如果你在尝试解决某些问题，请详细描述如何复现此问题。如果问题很难被复现，其他开发者和志愿者就很难进行调试。尽量只写出复现该问题的 最少步骤 （无额外插件）。
上传你的配置文件以及所有自定义过的代码，这可以使得大家能够重现问题或者看到你已经做出的尝试。
上传详细完整的输出日志以及backtraces信息（记得在执行pelican命令时加上 --debug 标记： pelican --debug content [...] ）

一旦做好了上述准备，就可以在 Pelican Discussions 中发起你的问题了。记得在请求中附上收集好的信息。

贡献代码¶

在提交代码修改前，请先询问是否需要此修改，以免你做的工作因为已知原因而被拒绝。想想要添加的新特性是否更适合以插件形式完成。可以通过如何获取帮助来帮助你作出决定。

另外，如果你的PR是为了解决一个目前没有在issue中出现过的问题，那么就没有必要先创建一个新的issue，而是可以直接提起PR。

使用Git与GitHub¶

创建一个新的分支来标记你做的修改（而不是直接在主分支中提交）。
不要把多个无关联的修复/特性修改放在同一个分支/拉去请求中。 如果当你在做新特性的时候发现了一个bug可以修复，但修复这个bug 不需要用到 这个新特性， 那么请另外创建一个分支并拉取请求。 类似的，任何对代码风格的格式化都应该在单独的请求中拉取。
在项目根目录下添加 RELEASE.md 文件，在其中包含release的类型（主要、次要、补丁），以及对项目改变的概述，这些内容会作为该release发布日志的一部分。下面是一个例子：
```
Release type: minor

Reload browser window upon changes to content, settings, or theme
```
在提交前使用 git diff --check 来检查是否有无意义的空白字符。
commit信息的第一行应该以现在时动词开头，并且第一行尽量保持在50字以下，并且包含相关联issue的编号（如果有的话）。例如： Ensure proper PLUGIN_PATH behavior. Refs #428. 如果此项提交 完全修复 了某项已报告的bug，请使用例如 Fixes #585 或 Fix #585 的语法（这样的话相关的issue会在PR合并后自动关闭）。
在第一行commit信息后添加一行空白行，再进行更多相关的细节描述。
压缩commit 来消除合并commits，确保你的commit历史记录是干净可读的。
在你发出PR后，持续集成（CI）系统会在所有支持的Python版本上运行测试套件，并且检查代码风格的合规性。如果出现了错误，你应该将其修复。（如果没有通过CI系统上的测试但是本地测试通过了，请再检查一下，确保在本地进行了所有CI系统中的检查）

贡献的质量标准¶

遵循项目的代码风格标准。详见开发环境
确保你的代码可以兼容 python的官方发布版本
请为你修改的内容添加文档与测试。未注有文档或没有对应测试的特性会被拒绝。
在Pelican支持的所有Python版本上 执行所有测试，以确保没有意料之外的问题。

若需要帮助或对以上指南有任何疑惑，还可以查看我们的 Git提示页面和请求帮助部分。

配置开发环境¶

在配置开发环境时往往有很多种方式，但下面的指南会使用 Pip 和 PDM 完成配置。这两个工具都可以用于管理虚拟环境，使得不同的Python项目相互隔离，这样就可以很方便的在不同的项目中使用不同的库（以及不同的库版本）。

请注意，要进行Pelican的开发，至少需要Python >=3.11

（可选） 若您想要安装PDM ，可以使用下面这条命令：

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

在Web浏览器中进入 Pelican的代码仓库，点击右上角的 Fork 按钮。然后克隆你自己的这份fork，最后添加项目的原仓库为远程仓库upstream：

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

通过下面的命令可以手动创建并激活一个虚拟环境：

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

安装必需的依赖并配置项目：

python -m pip install invoke
invoke setup

现在，你的本地开发环境就配置完成了！

开发¶

在配置好Pelican的本地开发环境后，请先为你的bug修复或特性增加创建一个分支：

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

在切换到新建的分支后，就可以开始对Pelican的文档或其他内容做更改了。

配置 `git blame` （可选）¶

git blame 会在文件中的行上标注有关最后一次修改该行的PR信息。对浅层变化（如格式化）进行批量更改可能会使这些信息变得不那么有用，因此我们维护一个包含此类更改的列表，以便忽略它们。运行以下命令在您的存储库中设置此配置，如果希望此设置适用于所有存储库，请添加 --global ：

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

就像在这篇文章中提到的，还可以进行一些可能有用的额外设置：

# 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

运行测试套件¶

每次对Pelican做出修改后，在测试方面需要做两个工作：检查是否能通过已有的测试、为新增特性或bug修复创建测试。请将自动化测试文件放在 pelican/tests 中，接着执行以下命令：

invoke tests

（执行 invoke -l 会列出可以调用的测试任务，关于此的更多文档请参阅 https://pyinvoke.org ）

除了运行测试套件外，还要确保修改了的部分遵循代码风格指南。可以通过下面的命令检查代码风格：

invoke lint

若存在不合规范风格的代码，大多数情况下可以通过下述命令自动纠正：

invoke lint --fix
invoke format

如果在修改过的代码中有地方违反了代码风格规范，请纠正并再次运行上述命令，直到全部纠正。但是若是发现违反代码风格的地方并不是你修改的，请忽略之，不要进行纠正。

在修改完代码，运行测试的过程中，你可能会看到测试失败中有提到“some generated files differ from the expected functional tests output” 。这可能是由于你对代码的修改影响到了Pelican的HTML输出，若输出的结果确实是你想要的，请更新功能测试所用的输出用例。请确保你安装了 en_EN.utf8 和 fr_FR.utf8 ，然后执行下述命令：

invoke update-functional-tests

你还可能会发现有一些测试由于缺少依赖（例如 Pandoc）而被跳过。这并不意味着通过了这些测试，请至少确保对代码的修改不会影响到这些被跳过的测试。

你应该在Pelican支持的所有Python版本下运行测试套件。一般会通过为每一个Python版本创建一个虚拟环境来实现这一点。Tox 是一个用于在 virtualenv 环境中自动运行测试的工具。

运行代码测试覆盖报告¶

经过测试的代码往往具有更好的健壮性。 Coverage 是一个用于衡量代码测试覆盖率的库执行下面的命令以调取之：

invoke coverage

该命令会展示总体覆盖率以及在每个文件上的覆盖率，甚至还会展示每一行的覆盖情况。同样也会有一份HTML格式的报告供您查看：

open htmlcov/index.html

构建文档¶

若你对文档进行过修改，请在commit前完成构建和检查：

invoke docserve

执行上述命令后，请在Web浏览器中打开 http://localhost:8000 来查看文档。在上述命令执行时，对文档做的任何修改应该会自动反映在浏览器中。

插件开发¶

要创建一个新的 Pelican插件，请参阅插件模板仓库以获得更为详细的指导。

若你想在已有 Pelican插件中做贡献，请先按前文所述步骤配置Pelican的本地开发环境，然后创建一个文件夹来存放克隆下来的插件仓库：

mkdir -p ~/projects/pelican-plugins

假设想要为Simple Footnotes插件做贡献，你应该先查看并fork Simple Footnotes 的Github仓库，然后克隆你自己fork的那一份，再添加原仓库作为Git远程仓库upstream：

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

同样地，为你想要进行的bug修复或特性添加创建一个分支：

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

完成修改并添加测试后，运行测试套件，并检查代码风格：

invoke tests
invoke lint

若存在不合规范风格的代码，大多数情况下可以通过下述命令自动纠正：

invoke lint --fix
invoke format

如果在自动格式化后仍存在代码风格上的问题，请手动修正这些问题，直到执行 invoke lint 时不再报告问题。

提交更改¶

通过了风格检查和所有测试后，请在项目的根目录下添加一个 RELEASE.md 文件，其中应包含发布的类型（major、minor、patch）以及代码变更的摘要，这份摘要会被用作更新日志的条目。下面是一个例子：

Release type: patch

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

commit你的更改，并push对应分支：

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

最后，前往Github，从你fork的仓库向原仓库提出PR。

日志技巧¶

请仔细斟酌合适的日志等级。

对于不重复的日志消息，使用一般的方式即可：

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

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

请不要自己格式化日志消息，而是使用在日志消息中使用 %s 并向logger传入参数。请务必遵循这一规则，因为Pelican的logger会自动预处理一些特殊的参数，例如exception。

限制低关联日志消息¶

如果同一日志消息会重复多次，你会希望限制这些多余的内容。使用 extra 命名参数来实现这一点：

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

可选的，如果通用日志消息需要格式化，可以添加 'limit_args' 参数并将其对应值设为一个元组。

限制数默认设为了 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

在日志中输出traceback信息¶

当在 except 块中进行日志记录时，你可能会希望同时输出traceback信息。可以简单地将 exc_info 参数设为 True 来实现这一功能。但是通过此方法输出的traceback信息会非常长，不便于理解。可以像下述代码一样将这些信息限制在 --debug 模式中：

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