Recommenders 开源贡献实战指南：基于 staging 分支的 PR 工作流与代码质量规范

Recommenders 开源贡献实战指南基于 staging 分支的 PR 工作流与代码质量规范【免费下载链接】recommendersBest Practices on Recommendation Systems项目地址: https://gitcode.com/gh_mirrors/re/recommenders推荐系统工具库 Recommendersgh_mirrors/re/recommenders欢迎来自社区的各类贡献从文档修订、Bug 修复到新增数据集、模型与评估指标。本文以仓库根目录的 CONTRIBUTING.md 为主体系统讲解该项目的贡献流程、分支策略、本地开发环境搭建、各类贡献的具体要求、代码风格约定与社区协作准则并结合仓库内的 setup.py、tests、SETUP.md 等源码与配置进行佐证。读完本文你将掌握向 Recommenders 提交一份合格 Pull Request 的完整链路从 Issue 讨论、Fork 与建分支到写测试、改代码、签名提交、通过 CI 门槛并合入staging。分支策略一切新功能落在 stagingmain 永远保持可用CONTRIBUTING.md 开篇用一段 TL;DR 概括了项目最核心的协作约定贡献流程速览项目使用staging分支接收所有新功能与修复。贡献者需要从staging创建自己的分支完成代码修改后向staging发起 Pull Request。这是 Recommenders 采用的两级分支策略two-level branching strategy。其设计动机在 tests/README.md 中有明确说明标准的一级分支策略中所有 PR 直接合入main一旦夜间构建nightly build失败main上就会留下坏代码而两级策略下开发者只向staging提交 PRmain仅在夜间构建全部通过之后才从staging更新从而保证main分支始终是可工作的稳定代码。标准贡献流程九个步骤CONTRIBUTING.md 给出了从零开始完成第一次贡献的九步流程下面逐一展开并补充仓库佐证。第 1 步先在 Issue 中讨论方案。使用项目的 open issues 讨论拟议的改动必要时创建 Issue 描述变更以收集反馈并使用官方提供的标签labels标记 Issue方便社区成员按兴趣快速筛选。对于较大的功能改动先讨论再动手可以避免返工。第 2 步Fork 仓库。Fork 后即可在本地自由修改与测试不影响上游。第 3 步从staging分支创建新分支。注意不要从main建分支。建议的分支命名格式是「用户名 描述性标题」例如gramhagen/update_contributing_docs第 4 步本地安装 recommenders 包。根据你要测试的功能选择正确的可选依赖extras并带上开发选项dev。例如 GPU 相关测试pip install -e .[gpu,dev]这里的-eeditable模式让本地代码改动即时生效便于开发迭代。extras的具体含义可以从 setup.py 的extras_require配置中确认Extra用途核心依赖来自 setup.pygpu运行 GPU 模型tensorflow2.8.4,2.16、torch2.0.1,3、nvidia-ml-py、tf-slimspark运行 Spark 模型pyspark3.3.0,4、pyarrow10.0.1dev开发环境black23.3.0、pytest7.2.1、pytest-cov、pytest-mockall以上全部gpu∪spark∪devexperimental未充分测试或需额外安装步骤的模型xlearn、vowpalwabbit、nni1.5、lightfm、scikit-surprise等SETUP.md 的 Setup for Developers 一节也给出了完整命令切换到staging分支后执行pip install -e .[dev,gpu]或安装全部依赖使用pip install -e .[all]。GPU 环境还需要先装好 CUDASpark 环境则需要 JDK。第 5 步编写一个能够复现 Issue 的测试。这是 TDD 式贡献的核心——先让测试失败再通过代码修复让它通过。Recommenders 的测试体系非常完善关于测试的分类与写法将在下文专门展开。第 6 步修改代码。第 7 步确保单元测试通过、代码风格与格式一致。项目的 Python 与 docstring 风格细节记录在项目 Wiki 的 Coding Guidelines 页面中可通过仓库首页的 Wiki 入口查看。从 setup.py 的devextra 可以看到项目使用black作为代码格式化工具、pytest系列作为测试工具链。第 8 步签名提交Signed commits。这是 Recommenders 的硬性要求提交必须签名否则 CI 测试会失败。签名方式参见项目 Wiki 的 How-to-sign-commits 页面。使用 GPG 签名提交的常见做法是在提交时添加-S参数例如git commit -S -m ...。第 9 步向staging分支发起 Pull Request。关于合并策略的更多细节staging 如何合入 main同样记录在项目 Wiki 中。贡献方向从文档到数据集、模型与指标CONTRIBUTING.md 将贡献划分为几个典型方向每个方向都有具体的质量要求。初次贡献从文档开始对开源新手或第一次接触 Recommenders 的开发者推荐从文档贡献入手可以完善仓库中的任意 README 文件或 Notebook。这类贡献门槛低、风险小却能帮助新贡献者快速熟悉仓库结构与代码组织。对更有经验的开发者则建议挑选 Issue 列表中标记的 Bug 进行修复。贡献新数据集新增数据集时需遵循两条原则最小化依赖优先使用requests库而非自定义库降低环境安装成本。仓库现有的数据集加载器如 movielens.py、criteo.py、mind.py都以轻量 HTTP 请求 本地缓存为主下载逻辑统一封装在 download_utils.py 中新数据集可复用这套基础设施可再分发性确保数据集公开可用且其许可证允许再分发。对应地数据集会在 tests/data_validation 中接受 schema 与数据可用性验证例如test_movielens.py会校验数据加载后的列名与规模。贡献新模型新增模型是社区贡献的主要方向之一要求也最为严格不要重复造轮子仓库中已实现的模型不要再提交一份相同实现。唯一的例外是你提供的是更优的实现或者你想把一个模型从 TensorFlow迁移到 PyTorch后者与项目PyTorch 优先的策略一致。最小化代码量优先提交解决问题所需的最少代码而不是引入一个完整的第三方库。如果借鉴了其他仓库的代码必须遵循其许可证并给出恰当的署名。Notebook 配套每个模型必须配套一个演示如何使用与训练的 Notebook放在 examples 目录下。从 tests/conftest.py 的notebooksfixture 可以看到仓库维护了一份完整的 Notebook 路径清单覆盖快速入门examples/00_quick_start/、模型深度剖析examples/02_model_collaborative_filtering/等分类。双层测试要求模型本身要用单元测试覆盖配套 Notebook 则要用功能测试覆盖。仓库 tests 目录按unit、smoke、functional等类别分层组织例如tests/unit/recommenders/models/下存放各类模型的单元测试tests/functional/examples/下存放 Notebook 的功能测试。贡献新指标评估指标metrics是另一类高价值贡献先优化再新增一个很好的切入点是对现有指标代码做性能优化。仓库在 tests/performance/recommenders/evaluation/test_python_evaluation_time_performance.py 中专门对评估函数执行时间设定了上限。CPU 与 PySpark 双版本新增指标时除了 PythonCPU实现还应考虑提供 PySpark 版本。仓库中 python_evaluation.py 与 spark_evaluation.py 成对存在正是这一要求的直接体现。边界测试编写测试时务必检查边界情况。例如新增误差类指标时要验证两个完全一致的数据集之间误差为 0。参照 tests/unit/recommenders/evaluation/test_python_evaluation.py 中的既有用例rmse(rating_true, rating_true) 0这类断言就是标准范式。通用原则无论贡献哪个方向以下四条仓库级约定都适用PyTorch 优先于 TensorFlow新代码优先使用 PyTorch 实现最小化依赖项目方统计显示仓库约 80% 的 Issue 与依赖问题相关因此每次引入新依赖都应三思许可证约束避免引入 GPL 及其他 copyleft 许可证的代码优先 MIT、Apache 等宽松许可证版权声明每个源文件开头需添加统一版权头Copyright (c) Recommenders contributors. Licensed under the MIT License.整个仓库包括 CONTRIBUTING.md 自身、setup.py、各测试文件均以这一版权头开头可对照参考。代码风格与质量Coding GuidelinesCONTRIBUTING.md 强调项目致力于维护高质量的代码使仓库中的工具易于理解、使用和扩展同时维持友好、建设性的协作环境。为此项目在 Wiki 中维护了一份详细的 Coding Guidelines 页面涵盖开发方法与风格的具体期望包括Python 与 docstring 风格提交信息与分支命名约定代码评审规范。从 setup.py 的devextra 可以看出工程化的配套black统一格式化、pytest、pytest-cov覆盖率、pytest-mockmock 支持。SETUP.md 还提到项目提供 VS Code Dev Containers 与 GitHub Codespaces 支持基于.devcontainer与 tools/docker/Dockerfile其中预置了 black-formatter、pylint 等扩展帮助贡献者在提交前就对齐代码风格。测试体系PR Gate 与夜间构建的双门槛Recommenders 的测试体系是社区协作质量的关键保障也是贡献者必须理解的基础设施。相关内容在 tests/README.md 中有系统阐述这里结合 tests/test_groups.yml 提炼与贡献者最相关的部分。两类测试流水线PR GatePull Request 后执行的快速测试集目标是在合入前验证代码没有破坏任何功能整体耗时控制在 20~30 分钟内其中单元测试等快测试会随每个 PR 运行。Nightly Builds异步执行的夜间构建可以运行数小时。大量耗时长、数据量大的测试如功能测试、大数据集验证只在这里执行。测试分类仓库 tests 目录按以下类别组织测试详见 tests/README.md类别目的运行时机Data validation校验输入/输出数据的 schema、可用性与规模PR GateUnit验证 Python 工具函数与 Notebook 能正确运行使用合成数据PR GateFunctional验证组件功能正确性如 RMSE 为正数使用真实数据NightlyIntegration验证组件间交互数据管道 ↔ 计算资源 ↔ 数据库视耗时而定Smoke大测试的精简版小数据集/单 epoch快速暴露明显错误NightlyPerformance度量计算时间与内存占用是否在限制范围内视情况Responsible AI强制公平性、透明性、可解释性、以人为本与隐私NightlySecurity检测 Python 包与 OS 层面的安全漏洞NightlyRegression保证新旧版本如 TF v1/v2代码行为一致视情况测试分组与时间预算CI 通过 tests/test_groups.yml 将上千个测试划分为nightly如group_cpu_001、group_gpu_001、group_spark、pr_gate如group_cpu_spark、group_gpu以及experimental三组配置每组标注了预估耗时。文件头部明确写有硬性预算对于 nightly任何组不得超过 45 分钟2700s对于 PR Gate任何组不得超过 15 分钟900s。贡献者新增测试后必须将其加入适当的测试分组并估算耗时保持组内总时间在预算之内——这一点在 tests/README.md 中被反复强调如果测试没有加入对应分组它就不会被执行。本地运行测试以devextra 安装环境后可以在仓库根目录直接运行 pytest。常用的三条命令摘自 tests/README.md注意在根目录执行# CPU 环境下运行工具库测试排除 notebooks/spark/gpu 标记 pytest tests -m not notebooks and not spark and not gpu --durations 0 --disable-warnings # CPU 环境下运行 Notebook 测试 pytest tests -m notebooks and not spark and not gpu --durations 0 --disable-warnings # 运行单个测试 pytest tests/data_validation/recommenders/datasets/test_mind.py::test_mind_url --durations 0 --disable-warnings测试标记markers在 pyproject.toml 中统一定义experimental、gpu、notebooks、spark。写测试时GPU 环境执行的测试需加pytest.mark.gpuSpark 环境执行的加pytest.mark.sparkNotebook 测试加pytest.mark.notebooks。测试数据则通过 tests/conftest.py 中的 fixture 提供如header列名配置、pandas_dummy合成评分数据、sparkSparkSession 会话、notebooksNotebook 路径映射等。测试编写规范tests/README.md 给出了明确的测试代码风格要求贡献者应遵循多个小测试优于一个大测试用pytest.fixture构造测试数据遵循assert computation value的显式断言模式例如assert results[precision] pytest.approx(0.330753)始终检查计算边界例如两个相同向量的 RMSE 应为 0比较值时用比较单例None、True、False时用is必要时用pytest.mark.skip/pytest.mark.skipif跳过因 OS 或上游问题无法解决的测试。社区协作准则Code of Conduct除官方 CODE_OF_CONDUCT.md 外Recommenders 团队还约定了三条具体的行为准则用于维护良好的协作环境。这些准则直接指导代码评审与 Issue 讨论的语气不指责个人Do not point fingers保持建设性。指出代码问题时对事不对人。CONTRIBUTING.md 给出的对照示例是应该说 This method is missing docstrings这个方法缺 docstring而不是 YOU forgot to put docstrings你忘了写 docstring。基于证据的代码反馈Provide code feedback based on evidence评审代码时尽量以论文、库文档、Stack Overflow 等证据支撑观点而非个人偏好。文档给出的示例是评审者发现指标实现采用类class而业界标准如 scikit-learn使用函数function时应引用 scikit-learn 文档说明应遵循行业标准。用提问代替下结论Ask questions do not give answers保持同理心用提问引导对方思考例如Would it make more sense if ...?如果……是不是更合理Have you considered this ...?你考虑过……吗小结与上手路径向 Recommenders 贡献代码并不复杂核心要点可归纳为五条分支纪律永远从staging建分支PR 目标也是stagingmain只接收通过全部测试的代码本地环境pip install -e .[dev,gpu|spark]按贡献方向选择 extra测试先行先写能复现 Issue 的测试再改代码并确保加入了 tests/test_groups.yml 的对应分组质量红线签名提交、代码风格统一black、遵循 PyTorch 优先与最小依赖原则、避免 copyleft 许可证协作礼仪Issue 先行讨论、评审基于证据、语气保持建设性。准备就绪后可以依次阅读 SETUP.md环境搭建、tests/README.md测试体系与 CODE_OF_CONDUCT.md行为规范然后从文档或 Bug 修复这类小贡献开始你的第一次提交。【免费下载链接】recommendersBest Practices on Recommendation Systems项目地址: https://gitcode.com/gh_mirrors/re/recommenders创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考