162 lines
11 KiB
Markdown
162 lines
11 KiB
Markdown
### 设计评审
|
||
|
||
若您的拉取请求涉及设计/用户界面改动，请务必添加相应标签以提醒设计团队。如需申请设计评审，请在PR中添加[需要设计反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback)标签。若存在需要更新设计/用户界面的PR，请使用[Figma库更新](https://github.com/WordPress/gutenberg/labels/Figma%20Library%20Update)标签。
|
||
|
||
需进行设计评审的变更类型指南：
|
||
- 基于既有设计的修改，需确认设计在变更后仍然有效
|
||
- 任何涉及视觉效果的改动
|
||
- 针对某个创意或探索性想法希望获得设计反馈
|
||
|
||
### 合并拉取请求
|
||
|
||
满足以下条件的拉取请求通常可被合并：
|
||
- 被认定对代码库具有重要价值
|
||
- 符合所有相关代码评审标准
|
||
- 必要时配备充分测试覆盖
|
||
- 经过所有潜在边界情况验证
|
||
- 已正确添加更新日志条目
|
||
- 经过原作者以外的成员评审
|
||
- 已[变基](/docs/contributors/code/git-workflow.md#keeping-your-branch-up-to-date)至`trunk`分支最新版本
|
||
|
||
最终合并决定由 **@wordpress/gutenberg-core** 团队作出。
|
||
|
||
GitHub上WordPress组织的所有成员均具备评审和合并拉取请求的权限。若您已完成PR评审并对代码质量有信心，请批准该拉取请求并通过评论提及**@wordpress/gutenberg-core**或参与该PR的核心成员。待其确认无异议后，您即可将PR合并至主干分支。
|
||
|
||
多数拉取请求将自动分配发布里程碑，但请确保已合并的PR获得相应分配。此举可建立代码变更的历史沿革记录，便于所有项目参与者（包括非技术人员）追溯信息。
|
||
|
||
### 关闭拉取请求
|
||
|
||
某些情况下，无论投入多少额外精力（如超出范围），拉取请求可能始终无法合并。此时应在关闭PR时礼貌地与贡献者沟通说明原因，这有助于促进未来的建设性参与。
|
||
|
||
请确保：
|
||
1. 感谢贡献者投入的时间与精力
|
||
2. 完整阐述关闭拉取请求的决策依据
|
||
3. 尽可能提供相关支持文档链接
|
||
|
||
参考沟通模板：
|
||
> 感谢____为本次拉取请求付出的时间。
|
||
>
|
||
> 关闭此PR的原因是____。进一步说明，____。
|
||
>
|
||
> 更多详情请参阅____和____。
|
||
|
||
## 团队架构
|
||
|
||
本项目使用两个GitHub团队：
|
||
- [Gutenberg核心团队](https://github.com/orgs/WordPress/teams/gutenberg-core)：由积极参与项目的成员组成，包括定期参加会议、参与问题分类会议、执行代码评审、开发功能与修复缺陷、执行插件及npm发布等。
|
||
|
||
- [Gutenberg团队](https://github.com/orgs/WordPress/teams/gutenberg)：由至少完成2-3项重要项目贡献的成员组成。
|
||
|
||
若您符合多项重要贡献已被代码库采纳的标准，并希望加入Gutenberg团队，欢迎在[#core-editor Slack频道](https://make.wordpress.org/chat/)提出申请。
|
||
|
||
## 项目管理
|
||
|
||
我们使用[GitHub项目](https://github.com/WordPress/gutenberg/projects)来追踪那些当前无需立即执行，但需要保留供未来参考的事项细节。
|
||
|
||
# 代码库管理
|
||
|
||
本文档为动态更新文档，旨在阐述我们如何协作管理 Gutenberg 代码库。若您希望提出修改建议，请通过提交议题进行讨论或直接向文档发起拉取请求。
|
||
|
||
本文档涵盖以下内容：
|
||
|
||
- [议题管理](#议题)
|
||
- [标签分类](#标签)
|
||
- [里程碑设置](#里程碑)
|
||
- [议题分类流程](#议题分类流程)
|
||
- [拉取请求](#拉取请求)
|
||
- [代码审查](#代码审查)
|
||
- [设计评审](#设计评审)
|
||
- [合并拉取请求](#合并拉取请求)
|
||
- [关闭拉取请求](#关闭拉取请求)
|
||
- [如何让您的拉取请求获得审核？](/docs/contributors/code/how-to-get-your-pull-request-reviewed.md)
|
||
- [项目管理](#项目)
|
||
|
||
## 议题管理
|
||
|
||
健康的议题列表应确保议题兼具相关性与可操作性。相关性指议题需符合项目当前优先级；可操作性则要求解决方案清晰明确。
|
||
|
||
对于无关或不可操作的议题应及时关闭，以免阻碍项目进展。不妨将议题列表视作工作台：堆积的杂物越多，有效工作空间就越受限。
|
||
|
||
### 标签分类
|
||
|
||
所有议题需配置[一个或多个标签](https://github.com/WordPress/gutenberg/labels)。
|
||
|
||
工作流标签以“Needs”开头，可根据需要灵活添加。理想情况下，每个工作流标签应有对应跟进团队（例如无障碍团队负责 `Needs Accessibility Feedback`，测试团队负责 `Needs Testing` 等）。
|
||
|
||
标有[优先级-高](https://github.com/WordPress/gutenberg/labels/%5BPriority%5D%20High)与[优先级-紧急](https://github.com/WordPress/gutenberg/labels/%5BPriority%5D%20OMGWTFBBQ)的议题需指定处理人员或纳入活跃里程碑。
|
||
|
||
求助类或操作指南类问题应首先发布于相关支持论坛。若不确定是否属于程序错误，支持团队或论坛志愿者将协助排查问题，为撰写有效的错误报告收集必要信息。
|
||
|
||
常见标签示例：
|
||
|
||
- [初试推荐](https://github.com/WordPress/gutenberg/labels/Good%20First%20Issue) - 适合新贡献者处理的议题。请通过评论申领任务，并在提交拉取请求时标注议题编号。
|
||
- [初审推荐](https://github.com/WordPress/gutenberg/labels/Good%20First%20Review) - 适合有意参与代码审查的新贡献者处理的拉取请求。
|
||
- [需无障碍反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Accessibility%20Feedback) - 影响无障碍访问的变更需经专项审查（如标记语言修改）。
|
||
- [需设计反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback) - 涉及设计或用户体验的变更需获得设计确认。
|
||
- [[类型]程序错误](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Bug) - 现有功能存在异常。
|
||
- [[类型]功能增强](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Enhancement) - 可提升 Gutenberg 使用体验的改进方案。
|
||
- [[类型]插件兼容性](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Plugin%20Interoperability) - 记录 Gutenberg 与插件/扩展的冲突情况。需通知插件作者并提供解决方案文档。
|
||
- [[状态]需补充信息](https://github.com/WordPress/gutenberg/labels/%5BStatus%5D%20Needs%20More%20Info) - 议题需补充关键信息方可推进处理，通常需要发起者配合完善。
|
||
|
||
[查阅完整标签目录](https://github.com/WordPress/gutenberg/labels)获取所有标签说明。
|
||
|
||
### 里程碑
|
||
|
||
我们将事项归入[里程碑](https://github.com/wordpress/gutenberg/milestones)以便更好地分类。事项会被添加至以`WordPress`开头的里程碑，而拉取请求则会被添加至以`(Gutenberg)`结尾的里程碑。
|
||
|
||
以下是一些您可能会看到的里程碑：
|
||
|
||
- [WordPress X.Y](https://github.com/WordPress/gutenberg/milestone/70)：为未来WordPress版本需要完成的任务。
|
||
- [X.Y (Gutenberg)](https://github.com/WordPress/gutenberg/milestone/85)：针对Gutenberg插件X.Y版本的拉取请求。
|
||
- [未来](https://github.com/WordPress/gutenberg/milestone/35)：这是经大家一致确认为有益但不属于其他分类的事项。
|
||
|
||
### 事项分类
|
||
|
||
为了保持事项列表的健康状态，需要定期进行分类。_分类_是指审查现有事项，确保它们具有相关性、可操作性，并包含所有必要信息。
|
||
|
||
任何人都可以帮助分类，但您需要拥有Gutenberg仓库的贡献者权限才能修改事项的标签或编辑其标题。
|
||
|
||
详情请参阅[分类贡献者指南](/docs/contributors/triage.md)。
|
||
|
||
## 拉取请求
|
||
|
||
Gutenberg针对所有代码和文档变更采用功能分支拉取请求工作流。从高层次看，流程如下：
|
||
|
||
1. 在本地检出一个新的功能分支。
|
||
2. 进行修改，并彻底测试。
|
||
3. 对修改满意后提交更改，并推送分支。
|
||
4. 打开您的拉取请求。
|
||
5. 如果您是拥有适当访问权限的常规贡献者，请正确标记和命名您的拉取请求（见下文）。
|
||
|
||
关于拉取请求的标记和命名，以下指南有助于更高效、有条理地编制变更日志。这些指南对常规贡献者尤为重要。但请不要因纠结于这些细节而阻碍您分享工作——出错是难免的，且易于修正！
|
||
|
||
- 处理实验性界面和功能时，应用`[Type] Experimental`标签，而非`Feature`、`Enhancement`等。
|
||
- 为技术包（脚本、create-block、添加React钩子等）开发新功能时，应用`[Type] New API`标签，而非`Feature`、`Enhancement`等。
|
||
- 修复项目内部工具的缺陷或进行增强时，应用`[Type] Build Tooling`标签，而非`Bugs`、`Enhancement`等。
|
||
- 在拉取请求标题中，与其描述为修复问题所做的代码变更，不如提及实际修复的缺陷。例如：与其说“在组件中检查可为空对象”，不如说“修复点击复制块按钮时编辑器崩溃的问题”。
|
||
|
||
除上述流程外，还有几点需要强调：
|
||
|
||
- 重要的拉取请求应有相关事项作为前提，该事项需明确待解决的问题，并允许在实际编写代码前讨论最合适的解决方案。
|
||
- 为使代码更易于合并，每个拉取请求应仅包含一个概念性变更。保持贡献的原子性可使拉取请求讨论聚焦于单一主题，并能够逐案审批变更。
|
||
- 不同的拉取请求可处理其关联事项中的不同项目或待办事项，若事项较为复杂，无需单个拉取请求覆盖单个事项。
|
||
|
||
### 代码审查
|
||
|
||
每个拉取请求除自动测试外，还需经过人工代码审查。代码审查的目标可概括为：
|
||
|
||
- **正确性**——变更是否实现了预期功能？
|
||
- **安全性**——恶意方是否会找到利用此变更的途径？
|
||
- **可读性**——数月后您自己能否理解此变更？
|
||
- **优雅性**——变更在整体风格和架构中是否协调？
|
||
- **利他性**——此变更如何为整体做出贡献？
|
||
|
||
_作为审查者_，您的反馈应聚焦于想法而非个人。力求理解、保持尊重，并专注于建设性对话。
|
||
|
||
_作为贡献者_，您的责任是从建议中学习，并根据反馈迭代您的拉取请求（如有需要）。力求协作，为整体做出最佳贡献。
|
||
|
||
鼓励所有愿意尝试的人参与代码审查。若您审查了拉取请求并对变更充满信心，请批准它。若您觉得它尚未完全准备好合并，请添加审查意见，说明在最终批准前需要另一组人员复核。这有助于过滤明显缺陷，并简化核心成员的审查工作。关注后续审查也有助于未来提升您的审查信心。
|
||
|
||
若您尚未准备好进行完整审查，可尝试在PR中评论。关于功能或变更缘由的提问同样有益。您也可以在不进行完整审查的情况下，对您理解的代码部分变更发表评论。
|
||
|
||
若您在获取审查方面遇到困难，请参阅：[如何让您的拉取请求获得审查？](/docs/contributors/code/how-to-get-your-pull-request-reviewed.md) |