From b4474b3401b0d557d21eba88274dcc11d4e3de2f Mon Sep 17 00:00:00 2001 From: Ta-Ching Chen Date: Mon, 9 Mar 2020 11:25:17 +0800 Subject: [PATCH] translation for new commit (dcf2c4debb483396b72643801cdd3c084d2964c7) --- zh-cn/review/developer/cl-descriptions.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/zh-cn/review/developer/cl-descriptions.md b/zh-cn/review/developer/cl-descriptions.md index b95b1db..61c95ad 100644 --- a/zh-cn/review/developer/cl-descriptions.md +++ b/zh-cn/review/developer/cl-descriptions.md @@ -10,9 +10,13 @@ CL 描述是进行了**哪些更改**以及**为何更改**的公开记录。CL * 完整的句子，使用祈使句。 * 后面跟一个空行。 -CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘要，后面跟一个空白行。这是将来大多数的代码搜索者在浏览代码的版本控制历史时，最常被看到的内容，因此第一行应该提供足够的信息，以便他们不必阅读 CL 的整个描述就可以获得这个 CL 实际上是做了什么的信息。 +CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘要，后面跟一个空白行。 -尝试让第一行保持简短，专注且切题的。清晰度和实用性对于读者而言应该是最重要的事。按照传统，CL 描述的第一行应该是一个完整的句子，就好像是一个命令（一个命令句）。例如，“**Delete** the FizzBuzz RPC and **replace** it with the new system.”而不是“**Deleting** the FizzBuzz RPC and **replacing** it with the new system.“ 但是，您不必把其余的描述写成祈使句。 +这会是版本控制历史记录摘要中显示的内容，因此第一行应该提供足够的信息，以便将来的代码搜索者不必阅读您的 CL或其全部描述即可了解您的 CL 的**实际功能**或与其他 CL 的区别。也就是说，第一行应该独立存在，从而使读者可以更快地浏览代码历史记录。 + +尝试让第一行保持简短，专注且切题的。清晰度和实用性对于读者而言应该是最重要的事。 + +按照传统，CL 描述的第一行应该是一个完整的句子，就好像是一个命令（一个命令句）。例如，“**Delete** the FizzBuzz RPC and **replace** it with the new system.”而不是“**Deleting** the FizzBuzz RPC and **replacing** it with the new system.“ 但是，您不必把其余的描述写成祈使句。 ## Body 是信息丰富的 {#informative} @@ -33,7 +37,7 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 - "Add convenience functions." - "kill weird URLs." -其中一些是真正的 CL 描述。他们的作者可能认为自己提供了有用的信息，却没有达到 CL 描述的目的。 +其中一些是真正的 CL 描述。儘管简短，却并没有提供足够有用的信息。 ## 好的 CL 描述 {#good} @@ -61,7 +65,7 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 第一行描述了 CL 的作用以及改变。其余的描述讨论了具体的实现，CL 的背景，解决方案并不理想，以及未来的可能方向。它还解释了为什么正在进行此更改。 -### 需要上下文的 小 CL +### 需要上下文的小 CL 示例: > Create a Python3 build rule for status.py. @@ -70,6 +74,10 @@ CL 描述的**第一行**应该是关于这个 CL 是**做什么**的简短摘 第一句话描述实际做了什么。其余的描述解释了为什么正在进行更改并为审查者提供了大量背景信息。 +## 自动生成的 CL 描述 + +部分 CL 是由工具生成。有可能的话，它们的描述也应遵循此处的建议。也就是说，他们的第一行应该简短，专注且切题的，独立存在，并且 CL 描述正文应包括足够充足详细信息，以帮助审阅者和将来的代码搜索者了解每个 CL 的作用。 + ## 在提交 CL 前审查描述 CL 在审查期间可能会发生重大变更。在提交 CL 之前检查 CL 描述是必要的，以确保描述仍然反映了 CL 的作用。