whichllm贡献指南：从提交issue到PR的完整开源协作流程

whichllm贡献指南：从提交issue到PR的完整开源协作流程

【免费下载链接】whichllmFind the local LLM that actually runs and performs best on your hardware. Ranked by real, recency-aware benchmarks, not parameter count. One command, run it instantly.项目地址: https://gitcode.com/GitHub_Trending/wh/whichllm

想要为 whichllm 这个强大的本地LLM选择工具做出贡献吗？本指南将详细介绍完整的开源协作流程，帮助新手从零开始参与项目开发。whichllm 是一个基于实时基准测试的本地大语言模型推荐工具，它能帮你找到在硬件上运行最佳的大语言模型。

🚀 为什么参与whichllm贡献？

whichllm 项目通过实时基准测试和智能硬件匹配，帮助用户找到最适合自己硬件的本地大语言模型。参与贡献不仅能提升你的开发技能，还能直接影响成千上万用户选择和使用AI模型的方式。

📋 快速入门：开发环境搭建

一键安装步骤

开始贡献前，首先需要搭建开发环境：

git clone https://gitcode.com/GitHub_Trending/wh/whichllm cd whichllm uv sync --dev

验证安装成功

运行简单的测试命令，确保环境配置正确：

uv run whichllm --help uv run pytest

🐛 如何提交有效的issue报告

问题反馈最佳实践

当遇到bug或发现问题时，使用项目提供的issue模板能大大提高沟通效率。在提交issue前，请确保包含以下关键信息：

1. 硬件信息：运行whichllm hardware获取详细硬件配置
2. 复现步骤：清晰描述如何重现问题
3. 期望与实际行为：明确说明预期结果和实际结果

使用issue模板

项目提供了标准化的issue模板，位于 .github/ISSUE_TEMPLATE/bug_report.yml。模板会自动引导你填写必要信息：

• 问题描述
• 复现步骤
• 硬件信息
• Python版本
• 操作系统
• whichllm版本

💡 功能建议与改进提案

新功能请求流程

如果你有改进whichllm的想法，可以使用功能请求模板。好的功能建议应该包含：

1. 问题描述：当前存在什么问题需要解决
2. 解决方案：你建议如何实现这个功能
3. 替代方案：考虑过的其他解决方案

功能请求模板位于 .github/ISSUE_TEMPLATE/feature_request.yml。

🔧 代码贡献完整流程

第一步：Fork仓库

首先fork主仓库到你的GitHub账户，这是开源贡献的标准起点。

第二步：创建功能分支

使用有意义的命名规范创建分支：

git checkout -b feature/your-feature-name git checkout -b fix/bug-description git checkout -b docs/documentation-update

第三步：进行代码修改

在进行修改时，请遵循项目代码规范：

• 使用类型提示（type hints）
• 保持与现有代码风格一致
• 为新功能添加测试用例

第四步：运行测试

提交代码前必须运行测试：

uv run pytest

测试文件位于 tests/ 目录，包含了各种功能测试。

📝 提交高质量的Pull Request

PR模板使用指南

提交PR时，请使用项目提供的PR模板，位于 .github/PULL_REQUEST_TEMPLATE.md。模板包含四个关键部分：

1. What：简要描述修改内容
2. Why：说明修改的原因和解决的问题
3. Testing：列出完成的测试项目
4. Notes：提供额外的上下文信息

PR检查清单

在提交PR前，请确保：

• ✅ 所有测试通过
• ✅ 新增功能有相应的测试用例
• ✅ 代码风格与项目保持一致
• ✅ 文档已相应更新
• ✅ 硬件相关修改已在真实硬件上测试

🎯 特定贡献类型指南

添加GPU支持

如果要添加新的GPU到带宽数据库，编辑 src/whichllm/constants.py 文件，添加GPU规格信息。

AI辅助代码贡献

whichllm项目欢迎AI辅助的代码贡献！项目理念是"实用至上"：让代码工作，适合项目，便于审查。如果你使用AI工具编写代码，请确保：

1. 理解生成的代码
2. 测试关键部分
3. 准备好解释或修复代码

文档改进

文档是项目的重要组成部分。你可以：

• 改进现有文档，如 docs/ 目录下的文件
• 添加使用示例
• 翻译文档（如现有的日语文档 docs/README.ja.md）

🧪 测试策略与最佳实践

测试框架使用

项目使用pytest作为测试框架。在编写测试时：

• 为新增功能编写单元测试
• 硬件检测相关的测试位于 tests/test_hardware.py
• CLI功能测试位于 tests/test_cli.py

硬件测试注意事项

如果贡献涉及硬件检测或GPU支持：

• 尽可能在真实硬件上测试
• 考虑不同操作系统（Linux、macOS、Windows）的兼容性
• 测试边缘情况和异常处理

🤝 社区协作与沟通

行为准则

参与贡献前，请阅读 CODE_OF_CONDUCT.md，了解社区行为规范。

代码审查流程

提交PR后，维护者会进行代码审查。审查过程中可能会：

• 提出改进建议
• 要求添加测试用例
• 讨论技术实现细节

请保持开放心态，积极回应审查意见。

持续集成

项目使用GitHub Actions进行持续集成，配置文件位于 .github/workflows/。每次提交都会自动运行：

• 代码风格检查
• 单元测试
• 集成测试

📊 项目结构与代码组织

了解项目结构能帮助你更快定位代码：

• 核心逻辑：src/whichllm/
• 硬件检测：src/whichllm/hardware/
• 模型处理：src/whichllm/models/
• 输出格式化：src/whichllm/output/
• 工具函数：src/whichllm/utils.py

🎉 开始你的第一个贡献

适合新手的任务

如果你是第一次参与开源贡献，可以从这些任务开始：

1. 文档改进：修复错别字，改进说明文档
2. 测试用例：为现有功能添加测试
3. 小bug修复：修复简单的逻辑错误
4. 示例添加：为功能添加使用示例

获取帮助

如果在贡献过程中遇到问题：

• 查看现有issue和PR寻找类似问题的解决方案
• 在issue中详细描述问题
• 参考项目文档和技术细节

📈 贡献后的跟进

跟踪进度

提交PR后，你可以：

• 定期检查CI运行状态
• 及时响应审查意见
• 根据需要更新代码

合并后的工作

PR合并后，你的贡献会成为项目的一部分！你可以：

• 继续关注相关功能的后续发展
• 帮助回答其他用户关于你贡献功能的问题
• 考虑参与更多功能开发

🔄 持续贡献与成长

成为常规贡献者

随着贡献经验的积累，你可以：

• 参与更复杂的功能开发
• 帮助审查其他人的PR
• 参与项目路线图讨论

技能提升

通过参与whichllm项目，你将获得：

• 开源协作经验
• Python开发技能
• 硬件检测和AI模型相关知识
• 测试驱动开发实践

现在就开始你的whichllm贡献之旅吧！每一个贡献，无论大小，都能帮助这个工具变得更好，让更多人受益于智能的本地大语言模型选择。🚀

记住：开源贡献不仅是写代码，更是学习、协作和成长的过程。期待在项目中看到你的贡献！

【免费下载链接】whichllmFind the local LLM that actually runs and performs best on your hardware. Ranked by real, recency-aware benchmarks, not parameter count. One command, run it instantly.项目地址: https://gitcode.com/GitHub_Trending/wh/whichllm