Paperless-ngx 贡献指南：分支模型、测试规范、PR 评审流程与新语言启用实战

Paperless-ngx 贡献指南分支模型、测试规范、PR 评审流程与新语言启用实战【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx本文基于 CONTRIBUTING.md 完整解析 Paperless-ngx 的贡献规范从PR 必须挂靠既有功能请求这一核心原则到 Python 版本策略与代码格式要求、main/dev/feature-X三分支模型、pytest 测试约定再到 non-trivial PR 的双人评审流程、AI 生成代码政策、翻译工作流以及新增语言时需要同步修改的四处代码位置。读完后你将清楚知道一个贡献如何从本地开发走到被合并以及如何为一个新语言完成从申请到代码启用的完整闭环。贡献总原则先有社区需求再谈实现CONTRIBUTING.md 开篇即给出全项目最重要的一条红线实现新功能或增强功能的 Pull Request几乎总是应当对应一个已存在的、有社区兴趣与讨论证据的功能请求feature request。这是为了平衡实现新功能与长期维护这些功能之间的成本。不符合该要求的 PR 可能被拒绝合并。如果你打算做一个较大的改动文档给出四条建议先发起讨论可能已有相似内容在开发中可以合并推进评估受益面问自己大多数用户是否会从你的改动中受益如果不是fork 项目自行维护可能是更好的选择避免影响无关用户一个好的改动是增强了想要它的用户体验且不影响不在乎它的用户了解合并流程见下文 PR 合并流程。若你的想法尚不满足上述条件规范建议直接开一个 feature request收集用户与维护者的反馈后再动手。Python 版本策略与代码风格支持的 Python 版本Paperless-ngx 当前支持Python 3.11、3.12、3.13 和 3.14。项目策略是至少支持最近三个 Python 版本并在版本 EOL停止维护后移除支持旧版本是否继续支持取决于依赖库是否允许不做保证。这一策略在 pyproject.toml 中有对应证据requires-python 3.11classifiers 中列出的恰好是 3.113.14 四个版本两者一致。代码格式化ruff项目使用ruff格式化 Python 代码配置集中在 pyproject.toml 的[tool.ruff]段约 L172-L247关键约束包括target-version py311、line-length 88lint 规则集基础E4/E7/E9/F之外extend-select追加了COM尾逗号、DJDjango 规则、Iimport 排序、PTH优先 pathlib、UPpyupgrade等数十组规则针对迁移文件*/migrations/*.py与测试文件*/tests/*.py分别放开了E501行长限制等个别规则isort.force-single-line true即每个 import 独占一行。此外项目通过 Git pre-commit 钩子在提交前强制格式化与 lint相关工具链是prekruff见 pyproject.toml 的lint依赖组prek~0.4.11、ruff~0.16.1。完整的钩子安装与开发环境搭建步骤见 docs/development.md 中 Code formatting with pre-commit hooks 一节执行uv sync --group dev安装开发依赖再用uv run prek install安装钩子。钩子会在提交时运行格式不合规会拒绝提交ruff 类钩子会自动改写失败文件git add后再试即可。分支模型main、dev 与 feature 分支仓库采用严格的三分支策略docs/development.md 与 CONTRIBUTING.md 描述一致分支语义约束main始终指向最新发布版本两个版本发布之间绝对不允许出现功能性改动仅允许文档/readme 变更dev包含下一个发布版本的全部变更所有功能改动都应从此分支发起feature-X实验性大改动最终会合并回dev但不一定进入下一个版本对贡献者而言实操含义很直接fork 后切出dev分支再开功能分支PR 目标一律指向dev而不是main。测试约定pytest 与覆盖率CONTRIBUTING.md 的要求是请格式化并测试你的代码在src/目录下执行pytest会同时生成 HTML 覆盖率报告帮助确认测试是否覆盖了关键路径。运行pytest前需先按 docs/development.md 的 Initial setup and first start 完成本地环境搭建。pyproject.toml 的[tool.pytest]段揭示了测试的默认行为贡献者可以据此理解 CI 将如何执行测试默认 addopts 启用覆盖率--cov html/xml 双报告、pytest-xdist 并行--numprocessesauto上限 16 进程loadscope分配策略、以及 junit xml 输出junitxmljunit.xml测试范围由testpaths限定为四个套件src/documents/tests/、src/paperless/tests/、src/paperless_mail/tests/、src/paperless_ai/tests/并跳过src/locale/、.venv/、src-ui/DJANGO_SETTINGS_MODULE paperless.settings测试环境通过[tool.pytest_env]注入固定环境变量例如PAPERLESS_SECRET_KEY、PAPERLESS_CACHE_BACKEND本地内存缓存、PAPERLESS_CHANNELS_BACKEND内存层——这解释了为什么测试不依赖真实 Redis定义了若干测试 markerlive依赖 Gotenberg/Tika/nginx 等外部服务的集成测试、searchTantivy 搜索后端、management管理命令、date_parsing等并开启strict_markers true即未声明的 marker 会直接报错[tool.coverage.run]将source设为src/omit 掉tests/、manage.py等文件与文档中看 HTML 覆盖率报告找测试盲区的说法对应。一个实用提醒来自 docs/development.md 测试小节跑测试时paperless.conf也会被加载但测试依赖默认配置因此除 DEBUG 外不要在其他配置项上做本地覆盖否则可能得到与 CI 不一致的结果。PR 合并流程non-trivial 评审PR 提交后会经过社区成员任意团队的有资格成员的 review、approve 与 merge自动化的代码测试与格式化检查必须通过。再次强调合并前提实现新功能/增强功能的 PR 应几乎总是对应一个既有的、有社区讨论的 feature request否则应改为先开 feature request。什么是 non-trivial PR被判定为non-trivial的 PR 在进入dev前要经过更严格的审查以确保代码质量与无副作用的完整功能。典型的 non-trivial 场景新增功能跨多个不同文件的大改动破坏性变更或废弃既有功能。评审流程通过常规的自动化测试与格式化检查PR 被指派并 到相应经验的团队例如后端改动 backend 团队开发团队人工检查并测试代码可能持续数天期间可能被要求修改代码或 rebase团队也可能要求 test 团队做额外测试至少两名团队成员批准后最终合并进dev。文档坦承这一流程可能较慢社区成员的时间表各异但目的是保证社区代码评审的彻底性。AI 生成代码政策CONTRIBUTING.md 对 AI 生成代码的立场是过程不禁止结果要负责最终 PR 中任何由 AI 生成的代码都必须明确标注其 AI 来源且不得侵犯版权保护完全或主要由 AI 生成的 PR 不会被接受。对贡献者而言这条政策的边界清晰用 AI 辅助补全、重构、写注释可以但提交前必须保证自己理解全部代码并如实披露 AI 参与的部分。翻译 Paperless-ngx两套资源与新增语言流程两套翻译资源src-ui/messages.xlf前端Angular翻译串最重要——大部分界面文案都在这里django.po管理后台Django admin的翻译串属于锦上添花。各语言的.po文件位于 src/locale/ 下如 src/locale/zh_CN/LC_MESSAGES/django.po。翻译时注意三条实践规则前端字符串多用于按钮、菜单项译文不宜明显长于英文原文翻译单元中的占位符placeholder通常代表标签名、文档名等动态内容点击即可复制翻译时原样保留复数表达式如{PLURAL_VAR, plural, 1 {one result} 0 {no results} other {placeholder results}}需要整句照抄结构只翻译内层{}里的内容例如德语{PLURAL_VAR, plural, 1 {Ein Ergebnis} 0 {Keine Ergebnisse} other {placeholder Ergebnisse}}。翻译工作通过 Crowdin 平台进行Crowdin 上的变更会自动推送回本仓库贡献者无需手工维护.xlf/.po文件。新增语言到代码库如果某语言已在 Crowdin 启用你要做的是贡献/修改既有译文如果希望项目支持一种新语言流程如下先在 Crowdin 的 paperless-ngx 项目确认该语言是否已启用若没有开一个 issue 申请issue 中需包含语言的英文名本地化名称可在 Crowdin 补充、ISO 语言代码、该语言常用的日期格式如dd/mm/yyyy语言在 Crowdin 启用并积累一定翻译后需要在代码中启用它——注意不需要手工添加.po或.xlf文件它们会从 Crowdin 自动生成导入需要修改以下四个文件顺序上按 locale 字母序插入en-us必须保持在列表顶部因为它是默认语言文件位置说明src-ui/angular.jsonprojects/paperless-ui/i18n/localesJSON 键下前端语言与 xlf 文件的映射例如zh-CN: src/locale/messages.zh_CN.xlfsrc/paperless/settings/init.pyLANGUAGES数组后端 Django 语言列表元组形如(zh-cn, _(Chinese Simplified))注释明确en-us必须首位以充当回退语言src-ui/src/app/services/settings.service.tsLANGUAGE_OPTIONS数组前端设置页语言选择项每项含code、name$localize本地化字符串、englishName、dateInputFormat必须含yyyy/mm/dd与申请时提交的日期格式对应src-ui/src/app/app.module.ts语言注册处import { registerLocaleData } from angular/common或angular/common/locales相应子模块并调用registerLocaleData否则 Angular 内置的日期/数字本地化在该语言下不生效熟悉 Git 的贡献者可以直接提交包含上述改动的 PR不熟悉的话在 issue 中说明即可会有其他开发者代劳。从源码结构看这三处语言清单后端LANGUAGES、前端LANGUAGE_OPTIONS、angular.jsonlocales必须保持一致后端决定 Django 侧可用语言前端决定设置页可选项与日期格式angular.json 决定构建时本地化哪些 xlf 文件——漏改任何一处都会导致该语言在某个层面消失。组织结构与维护机制组织与加入Paperless-ngx 是社区项目权限与责任分散在一个团队中以保证项目长期健康。当前拥有仓库完整管理员权限的成员为shamoon与stumpylog项目仍在积极寻找更多专职维护者。加入组织并不严格读完团队权限说明后若认为更高权限有助于你的贡献可直接联系管理员管理员也会不定期直接邀请活跃贡献者。仓库自动维护规则为了保持仓库整洁可管理项目对部分内容实行自动化处理来自 CONTRIBUTING.md Automatic Repository Maintenance 一节无法复现的 issue不活跃 7 天标记为 stale再 14 天不活跃后关闭已关闭的 issue、PR 与讨论30 天不活跃后锁定已标记答案的讨论自动关闭General/Support类别的讨论180 天不活跃后关闭功能请求若达不到热度阈值会被关闭180 天不活跃且 up-votes 80180 天后 5 票1 年后 20 票2 年后 40 票。所有线程都可以由维护者重新打开用户也随时可以为相关问题新开讨论。已关闭的功能请求依然可检索可作为新功能的灵感来源——这也呼应了前文PR 要挂靠既有 feature request的总原则feature request 本身就是社区需求的前置孵化器。【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考