Skip to content

Latest commit

 

History

History
182 lines (143 loc) · 5.91 KB

QUALITY_SCORING.md

File metadata and controls

182 lines (143 loc) · 5.91 KB

RepoSense 质量评分算法

RepoSense 使用一套综合的质量评分算法来评估代码仓库的整体质量。评分范围为 0.0 - 10.0 分,基于现代软件开发的最佳实践。

📊 评分维度

质量评分基于以下 7 个关键维度:

1. 📖 README 文档 (2.0分)

  • 检测标准: 项目根目录或二级目录下存在 README 文件
  • 支持格式: README.md, README.rst, README.txt, README
  • 重要性: 高 - 项目文档是用户和贡献者了解项目的第一步

2. ⚖️ 开源许可证 (1.5分)

  • 检测标准: 项目根目录或二级目录下存在许可证文件
  • 支持格式: LICENSE, LICENSE.txt, LICENSE.md, COPYING
  • 重要性: 中高 - 明确的许可证对开源项目至关重要

3. 🧪 测试代码 (2.0分)

  • 检测标准: 存在测试目录或测试文件
  • 测试目录: test/, tests/, tests/, spec/, specs/
  • 测试文件: test., spec., test_, spec_
  • 重要性: 高 - 测试是代码质量和可靠性的保证

4. 🔄 持续集成 (1.5分)

  • 检测标准: 存在 CI/CD 配置文件
  • 支持平台:
    • GitHub Actions: .github/workflows/
    • GitLab CI: .gitlab-ci.yml
    • Travis CI: .travis.yml
    • Jenkins: Jenkinsfile
    • CircleCI: .circleci/config.yml
  • 重要性: 中高 - 自动化流程提高开发效率和代码质量

5. 📚 文档目录 (1.0分)

  • 检测标准: 存在专门的文档目录
  • 目录名称: docs/, documentation/, doc/
  • 重要性: 中 - 详细文档提升项目可维护性

6. 🌍 语言多样性 (1.0分)

  • 评分逻辑:
    • 1-3 种编程语言: 1.0 分 (最佳实践)
    • 4+ 种编程语言: 0.5 分 (可能存在维护复杂性)
    • 0 种语言: 0 分
  • 重要性: 中 - 适度的语言多样性体现技术栈合理性

7. 🔧 框架使用 (1.0分)

  • 检测标准: 使用了已知的开发框架
  • 检测框架: React, Vue, Angular, Django, Flask, Spring Boot, Rails 等
  • 重要性: 中 - 框架使用体现结构化开发

🧮 计算公式

质量评分 = (实际得分 / 总分 10.0) × 10.0

总分为所有维度分值之和:2.0 + 1.5 + 2.0 + 1.5 + 1.0 + 1.0 + 1.0 = 10.0 分

📈 评分等级

分数范围 等级 描述
8.0 - 10.0 🌟 优秀 遵循了大部分最佳实践,项目质量很高
6.0 - 7.9 👍 良好 具备基本的工程实践,还有提升空间
4.0 - 5.9 🔄 一般 缺少一些重要的工程实践
2.0 - 3.9 ⚠️ 待改进 缺少多个关键实践,需要重点改进
0.0 - 1.9 🚨 需要关注 几乎没有工程实践,建议全面改进

🎯 实际案例

高质量项目示例 (9.0分)

✅ README.md 存在         (+2.0)
✅ MIT LICENSE 存在       (+1.5)
✅ tests/ 目录存在        (+2.0)
✅ .github/workflows/ 存在 (+1.5)
✅ docs/ 目录存在         (+1.0)
✅ 使用 2 种语言 (Go, JS)  (+1.0)
❌ 未检测到框架           (+0.0)
总分: 9.0/10.0

中等质量项目示例 (5.5分)

✅ README.md 存在         (+2.0)
❌ 无许可证文件           (+0.0)
✅ test/ 目录存在         (+2.0)
❌ 无 CI 配置            (+0.0)
❌ 无专门文档目录         (+0.0)
✅ 使用 1 种语言 (Python) (+1.0)
✅ 检测到 Flask 框架      (+1.0)
总分: 6.0/10.0

低质量项目示例 (2.5分)

✅ README.md 存在         (+2.0)
❌ 无许可证文件           (+0.0)
❌ 无测试代码             (+0.0)
❌ 无 CI 配置            (+0.0)
❌ 无专门文档目录         (+0.0)
✅ 使用 1 种语言 (Python) (+1.0)
❌ 未检测到框架           (+0.0)
总分: 3.0/10.0

💡 提升质量评分的建议

快速提升 (短期内可完成)

  1. 添加 README.md - 描述项目目的、安装和使用方法 (+2.0分)
  2. 添加 LICENSE - 选择合适的开源许可证 (+1.5分)
  3. 创建 docs/ 目录 - 整理项目文档 (+1.0分)

中期改进 (需要一些开发工作)

  1. 编写测试代码 - 添加单元测试、集成测试 (+2.0分)
  2. 选择合适框架 - 使用成熟的开发框架 (+1.0分)

长期优化 (需要流程建设)

  1. 配置 CI/CD - 设置自动化构建、测试、部署 (+1.5分)

🔍 检测详情

README 检测

  • 文件名模式: README*, readme*
  • 支持扩展名: .md, .rst, .txt, 无扩展名
  • 检测范围: 项目根目录及一级子目录

许可证检测

  • 文件名模式: LICENSE*, COPYING*
  • 支持扩展名: .txt, .md, 无扩展名
  • 检测范围: 项目根目录及一级子目录

测试检测

  • 目录检测: test/, tests/, __tests__/, spec/, specs/
  • 文件模式: *test.*, *spec.*, test_*, spec_*
  • 特殊文件: pytest.ini, jest.config.js, karma.conf.js

CI 检测

  • GitHub Actions: .github/workflows/*.yml
  • GitLab CI: .gitlab-ci.yml, .gitlab-ci.yaml
  • Travis CI: .travis.yml
  • CircleCI: .circleci/config.yml
  • Jenkins: Jenkinsfile
  • Azure Pipelines: azure-pipelines.yml

框架检测

基于配置文件和依赖分析:

  • 前端: React, Vue, Angular, Svelte
  • 后端: Django, Flask, FastAPI, Express, Spring Boot
  • 移动端: React Native, Flutter
  • 桌面端: Electron, Tauri

⚙️ 配置说明

质量评分会在以下命令中显示:

# 分析单个或多个仓库
reposense analyze /path/to/repos

# 搜索时显示质量评分
reposense metadata search --min-quality 7.0

# 查看详细元数据
reposense metadata show /path/to/repo

🔧 自定义建议

虽然当前评分算法已经覆盖了主要的质量维度,但不同类型的项目可能有不同的关注点:

  • 库项目: 更注重文档和测试
  • 应用项目: 更注重 CI/CD 和部署配置
  • 研究项目: 更注重 README 和示例代码
  • 企业项目: 更注重许可证和安全配置

未来版本可能会支持按项目类型的差异化评分策略。


最后更新: 2025-06-22 RepoSense 版本: v1.0.0