贡献

相关源文件

• .github/CODEOWNERS
• .github/ISSUE_TEMPLATE/BUG_REPORT.yml
• .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml
• .github/workflows/codeql.yml
• README.md
• api/openapi.yml
• apps/api/package.json
• apps/api/prisma/dev.db
• apps/api/prisma/migrations/20241009081140_init/migration.sql
• apps/api/prisma/migrations/migration_lock.toml

本文档提供了贡献 RealWorld 项目的全面指南。它涵盖了开发工作流程、项目设置、编码标准和提交贡献的流程。

RealWorld 项目旨在展示使用各种前端和后端技术进行真实应用程序开发的实例，所有这些都遵循标准化的 API 规范。本指南重点介绍如何贡献到核心存储库 https://github.com/gothinkster/realworld，其中包含 API 规范、参考实现和文档。

有关实现 RealWorld 新前端或后端的详细信息，请参阅项目概述。

目录

• 开发环境设置
• 项目结构
• 贡献工作流程
• 拉取请求指南
• 测试您的更改
• GitHub 工作流
• 问题报告

开发环境设置

要为 RealWorld 项目做出贡献，您需要设置本地开发环境

1. Fork 存储库 - 在 GitHub 上创建 RealWorld 存储库的副本
2. Clone 您的 Fork - git clone https://github.com/YOUR_USERNAME/realworld.git
3. 安装依赖项 - 导航到克隆的存储库并使用 pnpm 安装依赖项

该项目使用 Turbo 来协调多个包的构建过程。主要的开发命令是

对于 API 开发，您可以为数据库填充测试数据

来源：apps/api/package.json3-9

项目结构

了解 RealWorld 项目的结构对于做出有效贡献至关重要。存储库的组织结构如下：

realworld/
├── api/ - API specification and testing tools
│   ├── openapi.yml - API definition
│   ├── Conduit.postman_collection.json - Postman tests
│   └── run-api-tests.sh - Test runner script
├── apps/ - Application implementations
│   ├── api/ - Reference API implementation
│   │   ├── prisma/ - Database schema and migrations
│   │   └── server/ - API server code
│   └── documentation/ - Documentation site
├── .github/ - GitHub configuration (workflows, templates)
└── media/ - Assets and images

对贡献者最重要的组成部分是：

关键组件关系

来源：api/openapi.yml api/run-api-tests.sh apps/api/prisma/migrations/20241009081140_init/migration.sql

贡献工作流程

下图说明了为 RealWorld 项目做出贡献的典型工作流程

分步贡献流程

1. Fork 存储库：点击 GitHub 存储库上的“Fork”按钮创建您的副本。

2. 克隆您的派生:

3. 设置上游远程仓库:

4. 创建功能分支:

5. 进行更改：按照编码标准实现您的功能或修复。

6. 运行测试：确保所有测试都通过

7. 提交您的更改:

8. 推送到您的 Fork:

9. 创建 Pull Request：转到原始 RealWorld 存储库，并从您的 Fork 创建 PR。

来源：README.md

拉取请求指南

为确保您的贡献能够快速被接受，请遵循以下指南：

1. 清晰的 PR 标题：提供一个清晰、简洁的标题，概括您的更改。

2. 详细说明：在 PR 描述中

   • 解释您的更改的作用
   • 使用格式 Fixes #123 引用相关问题
   • 描述您如何测试您的更改

3. 保持 PR 聚焦：为不相关的更改提交单独的 PR，以便于审查。

4. 更新文档：如果您的更改影响了面向用户的功能，请更新相关文档。

5. 代码质量:

   • 遵循现有的代码风格和格式
   • 保持更改的简洁和专注
   • 为复杂的逻辑添加适当的注释

6. 测试：所有 PR 都应包含足够的测试，以覆盖新功能或错误修复。

来源：.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml .github/ISSUE_TEMPLATE/BUG_REPORT.yml

测试您的更改

RealWorld 项目强调彻底的测试。在提交 PR 之前，请确保您的更改通过了所有现有测试，并为新功能添加了测试。

API 测试

对于 API 更改，RealWorld 使用 Postman 集合，并通过 Newman 执行 API 测试

此脚本针对 API 实现运行 Postman 集合，并验证其是否符合 RealWorld API 规范。

测试您的 API 实现

测试套件验证

• 身份验证端点
• 用户和个人资料操作
• 文章创建、更新和删除
• 评论功能
• 收藏/取消收藏操作
• 标签检索

来源：api/openapi.yml

GitHub 工作流

RealWorld 项目使用 GitHub Actions 进行持续集成。当您提交 PR 时，这些工作流程会自动运行以检查您的代码

CodeQL 分析

存储库有一个 CodeQL 分析工作流，它会对 JavaScript 代码运行安全检查

CodeQL 工作流每周运行一次或按需运行，以识别代码库中潜在的安全问题。

来源：.github/workflows/codeql.yml

问题报告

如果您发现 bug 或想请求功能，请使用 GitHub issue 模板，以确保您提供了所有必要的信息

Bug 报告

对于 bug 报告，请使用 bug 报告模板并包含：

• 问题的范围（前端、后端等）
• 对问题的清晰描述
• 重现步骤
• 预期行为与实际行为

功能请求

对于功能请求，请使用功能请求模板并包含：

• 请求的范围
• 对功能的详细描述
• 为项目带来的潜在好处

来源：.github/ISSUE_TEMPLATE/BUG_REPORT.yml .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml

结论

为 RealWorld 项目做出贡献是提高您的开发技能同时帮助创建宝贵开发者资源的好方法。通过遵循这些指南，您将使您和项目维护者的贡献过程顺畅而高效。

请记住，RealWorld 项目由志愿者维护，因此请在所有互动中保持耐心和尊重。我们感谢您对贡献的兴趣！

如有其他问题，请加入 GitHub Discussions 上的讨论。

来源：README.md14