开发指南

相关源文件

• .gitignore
• .husky/.gitignore
• .husky/pre-commit
• .vercelignore
• .vscode/extensions.json
• .vscode/settings.json
• CONTRIBUTING.md
• jest.config.js
• package-lock.json
• package.json

本指南为希望为GitHub Readme Stats项目贡献的开发者提供了全面的说明。它涵盖了环境设置、开发工作流程、测试和贡献指南。有关整体系统架构的信息，请参阅系统架构。

先决条件

在开始为GitHub Readme Stats贡献之前，请确保您已安装以下软件

• Node.js（版本18.0.0或更高版本，如package.json中所指定）
• npm（随Node.js一起提供）
• 一个用于本地开发的Vercel账户
• Git 用于版本控制

来源：package.json74-76 CONTRIBUTING.md30-32

设置开发环境

按照以下步骤设置您的本地开发环境

1. Fork 并克隆仓库

2. 安装依赖项

3. 安装Vercel CLI

4. 配置Vercel项目

   按照提示将您的本地项目链接到您的Vercel账户。

5. 启动开发服务器

   这将启动一个本地服务器，地址为http://:3000。

6. 本地访问卡片 卡片将可在此处访问：http://:3000/api?username=YOUR_USERNAME

来源：CONTRIBUTING.md28-39 package.json11-76

开发工作流

来源：CONTRIBUTING.md11-19 package.json21-35 .husky/pre-commit1-4 .vscode/settings.json1-6

分支

1. 从master分支创建一个新分支来处理您的功能或错误修复

2. 在此分支上进行更改。

3. 使用有意义的提交消息提交您的更改。

代码风格和格式化

该项目使用ESLint和Prettier来维护代码质量和保持格式一致

• 代码检查：运行npm run lint来检查代码质量问题
• 代码格式化：运行npm run format来自动格式化您的代码

已通过Husky配置预提交钩子，以便在每次提交前运行测试、代码检查和格式化检查。

来源：package.json30-33 .husky/pre-commit1-4 .vscode/settings.json1-6

项目结构

GitHub Readme Stats项目具有良好的结构，可以将关注点分开并提高可维护性。

来源：package.json11-21

测试

测试是开发过程中至关重要的部分。本项目使用Jest进行测试。

运行测试

• 运行所有测试：npm test
• 在监视模式下运行测试：npm run test:watch
• 更新快照：npm run test:update:snapshot
• 运行E2E测试：npm run test:e2e
• 运行基准测试：npm run bench

编写测试

测试位于tests/目录中，其结构与源代码相对应。在添加新功能时，请确保

1. 为新函数编写单元测试
2. 在修改功能时更新现有测试
3. 在提交PR之前确保所有测试都通过

来源：package.json22-26 jest.config.js1-13

调试

该项目支持使用Visual Studio Code进行调试

1. VS Code调试：您可以使用VS Code中的“Node.js：Attach to process”配置进行调试。
2. Jest扩展调试：使用VSCode Jest扩展直接在编辑器中调试测试。

来源：CONTRIBUTING.md40-41 .vscode/extensions.json1-8

主题使用

卡片的外观可以通过主题系统进行定制。

注意：为了减少维护工作量，本项目目前暂停添加新主题。

如果您需要预览主题

来源：CONTRIBUTING.md43-48 package.json27

翻译

要添加新语言

1. 编辑src/translations.js文件
2. 向每个对象添加一个新属性，键为ISO 639-1语言代码
3. 翻译所有字符串

来源：CONTRIBUTING.md51-54

实用脚本

该项目包含多个实用脚本

脚本	目的
theme-readme-gen	生成主题文档
preview-theme	预览PR的主题
close-stale-theme-prs	关闭过期的主题PR
generate-langs-json	更新语言数据

来源：package.json26-29

拉取请求流程

1. 确保所有本地测试均已通过
2. 使用Prettier格式化您的代码
3. 创建一个到master分支的拉取请求
4. 填写PR模板，提供有关您更改的详细信息
5. 等待CI检查通过
6. 处理维护人员提出的任何反馈

该项目使用GitHub Actions进行CI/CD，它会在您的PR上自动运行测试、代码检查和其他检查。

来源：CONTRIBUTING.md11-19

环境变量

对于本地开发，您可能需要设置环境变量

1. 在根目录创建一个.env文件
2. 添加您的GitHub个人访问令牌（如果需要私有统计信息）

   PAT_1=your_github_token
   

来源：.gitignore1-2

常见开发任务

任务	命令
运行测试	npm test
格式化代码	npm run format
检查格式	npm run format:check
运行 linting	npm run lint
启动开发服务器	vercel dev
生成主题文档	npm run theme-readme-gen

来源：package.json21-35

许可信息

所有对GitHub Readme Stats的贡献都遵循MIT许可证。在提交代码之前，请确保您理解并同意此许可证。

来源：CONTRIBUTING.md56-58 package.json37