trpc.group/trpc-go/trpc-go@v1.0.3/CONTRIBUTING.zh_CN.md (about)

     1  [English](CONTRIBUTING.md) | 中文
     2  
     3  # 如何贡献
     4  
     5  感谢您对 tRPC-Go 的关注和支持！
     6  
     7  我们欢迎并感激任何形式的贡献，包括但不限于提交 issue、提供改进建议、改进文档、修复错误和添加功能。
     8  本文档旨在为您提供详细的贡献指南，以帮助您更好地参与项目。
     9  在贡献之前，请仔细阅读本指南并确保遵循这里的规则。
    10  我们期待与您共同努力，使这个项目变得更好！
    11  
    12  ## 在贡献代码之前
    13  
    14  项目欢迎代码补丁，但为了确保事情得到良好协调，您应该在开始工作之前讨论任何重大变更。
    15  建议您在 issue 跟踪器中表明您的贡献意图，可以通过[认领现有 issue](https://github.com/trpc-group/trpc-go/issues)或[创建新 issue](https://github.com/trpc-group/trpc-go/issues/new) 来实现。
    16  
    17  ### 查看 issue 跟踪器
    18  
    19  无论您已经知道要做哪些贡献，还是正在寻找想法，[issue 跟踪器](https://github.com/trpc-group/trpc-go/issues)始终是您的第一个去处。
    20  issue 会被分类以管理工作流程。
    21  
    22  大多数 issue 都会被标记为以下工作流标签之一：
    23  - **NeedsInvestigation**：issue 尚未完全理解，需要分析以了解根本原因。
    24  - **NeedsDecision**：issue 相对已经理解得很好，但 tRPC-Go 团队尚未决定解决 issue 的最佳方法。
    25    在编写代码之前最好等待决策。
    26    如果一段时间内没有决策且您有兴趣处理处于这种状态的 issue，请随时在 issue 评论中“ping”维护者。
    27  - **NeedsFix**：issue 已完全理解，可以编写代码进行修复。
    28  
    29  ### 为任何新问题打开一个 issue
    30  
    31  除非是非常细小的变更，否则所有贡献都应与现有 issue 有关。
    32  请随时打开一个 issue 并讨论您的计划。
    33  这个过程让每个人都有机会验证设计，有助于防止工作重复，确保想法符合语言和工具的目标。
    34  在编写代码之前，还可以检查设计是否合理；代码审查工具并非用于高层次的讨论。
    35  
    36  在提交 issue 时，请确保回答以下五个问题：
    37  1. 您正在使用哪个版本的tRPC-Go？
    38  2. 您正在使用哪个操作系统和处理器架构（go env）？
    39  3. 您做了什么？
    40  4. 您期望看到什么？
    41  5. 您实际看到的是什么？
    42  
    43  关于变更提案，请参阅向 [tRPC-Proposals](https://github.com/trpc-group/trpc/tree/main/proposal) 提议变更。
    44  
    45  ## 贡献代码
    46  
    47  遵循 [GitHub 流程](https://docs.github.com/en/get-started/quickstart/github-flow)来[创建 GitHub PR(Pull Request)](https://docs.github.com/en/get-started/quickstart/github-flow#create-a-pull-request)。
    48  
    49  如果你是第一次向 tRPC-Go 项目提交 PR，那么在该 PR 的对话栏中会提醒你签署并提交[贡献者许可协议](https://github.com/trpc-group/cla-database/blob/main/Tencent-Contributor-License-Agreement.md)。
    50  只有当你签署过贡献者许可协议，你提交的 PR 才有可能被接受。
    51  请记住以下几点：
    52  
    53  - 确保您的代码符合项目的代码规范。
    54    这包括但不限于代码风格、注释规范等。这有助于我们维护项目的整洁性和一致性。
    55  - 在提交 PR 之前，请确保您已在本地测试过您的代码。 确保代码没有明显的错误并且可以正常运行。
    56  - 要使用新代码更新拉取请求，只需将其推送到分支； 您可以添加更多提交，也可以 rebase 并 force-push（两种风格都可以接受）。
    57  - 如果请求被接受，所有提交将被压缩，最终提交描述将由 PR 的标题和描述组成。
    58    单个提交的描述将被丢弃。 请参阅以下“编写良好的提交消息”以获取一些建议。
    59  
    60  ### 编写良好的提交消息
    61  
    62  tRPC-Go 中的提交消息遵循一套特定的约定，我们将在本节中讨论。
    63  
    64  以下是一个良好的示例：
    65  > math: improve Sin, Cos and Tan precision for very large arguments
    66  >
    67  > The existing implementation has poor numerical properties for large arguments, so use the McGillicutty algorithm to improve accuracy above 1e10.
    68  >
    69  > The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
    70  >
    71  > Fixes #159
    72  >
    73  > RELEASE NOTES: Improved precision of Sin, Cos, and Tan for very large arguments (>1e10) 
    74  
    75  #### 第一行
    76  
    77  变更描述的第一行通常是一个简短的一行摘要，描述变更的内容，并以主要受影响的包为前缀。
    78  
    79  一个经验法则是，它应该被写成完成句子 "This change modifies tRPC-Go to _____." 这意味着它不以大写字母开头，不是一个完整的句子，而且确实概括了变更的结果。
    80  
    81  在第一行之后空一行。
    82  
    83  #### 主要内容
    84  
    85  描述的其余部分应该详细说明，为变更提供上下文并解释它的作用。
    86  像在 tRPC-Go 中的注释一样，使用正确的标点符号写完整的句子。
    87  不要使用 HTML、Markdown 或任何其他标记语言。
    88  添加任何相关信息，例如如果变更影响性能，请添加基准数据。
    89  [benchstat](https://godoc.org/golang.org/x/perf/cmd/benchstat)工具通常用于为变更描述格式化基准数据。
    90  
    91  #### 引用 issue
    92  
    93  特殊表示法 "Fixes #12345" 将变更与 tRPC-Go issue 跟踪器中的 issue 12345关联。
    94  当此变更最终应用时，issue 跟踪器将自动将该 issue 标记为已修复。
    95  
    96  - 如果有相关 issue，请在此评论中添加 `Fixes #12345` 或` Updates #12345`（如果这不是完整的修复）
    97  - 如果涉及到的仓库不是 `trpc-go`，则可以使用 `owner/repo#issue_number` 语法：`Fixes trpc-group/tnet#12345`
    98  
    99  #### PR 类型标签
   100  
   101  PR 类型标签用于标识当前 PR 变更所属的类型，为后续发布版本提供参考。这有助于发布团队在更快的发布周期里，准确识别当前周期内所有类型的问题。
   102  
   103  对于所有 PR，必须设置以下之一的 PR 类型标签：
   104  
   105  - type/bug: 修复新发现的 bug。
   106  - type/enhancement: 添加测试，重构内部代码。
   107  - type/feature: 新功能。
   108  - type/documentation: 添加文档。
   109  - type/api-change: 添加、删除或更改 API。
   110  - type/failing-test: CI 测试用例偶发失败。
   111  - type/performance: 改进性能的变更。
   112  - type/ci: 更改 CI 配置文件和脚本。
   113  
   114  #### 发布说明
   115  
   116  对于任何造成用户可见更改的 PR，都需要提供发布说明。这可能包括：
   117  
   118  - 用户可见的关键 bug 修复
   119  - 显著的功能增加
   120  - 功能弃用或移除
   121  - API 更改
   122  - 文档添加
   123  
   124  如果当前 PR 没有用户可见的变更，例如代码内部重构，添加测试用例等情况，发布说明内容填为 'NONE'，这个 PR 的变更就不会记录在下个版本的 CHANGELOG 中；如果当前 PR 有用户可见的变更，发布说明内容需要按照实际情况填写，尽量不要涉及技术细节，在用户视角描述当前变更会造成的影响。
   125  
   126  发布说明是用户即将使用或升级到 tRPC-Go 特定版本时的最重要参考点之一。
   127  
   128  ## 其他主题
   129  
   130  ### 版权声明
   131  
   132  tRPC-Go 代码仓库中的文件不列出作者姓名，以避免混乱并避免不断更新列表。
   133  而您的名字将出现在变更日志中。
   134  
   135  您贡献的新文件应使用标准版权声明：
   136  ```go
   137  //
   138  //
   139  // Tencent is pleased to support the open source community by making tRPC available.
   140  //
   141  // Copyright (C) 2023 THL A29 Limited, a Tencent company.
   142  // All rights reserved.
   143  //
   144  // If you have downloaded a copy of the tRPC source code from Tencent,
   145  // please note that tRPC source code is licensed under the  Apache 2.0 License,
   146  // A copy of the Apache 2.0 License is included in this file.
   147  //
   148  //
   149  ```
   150  
   151  代码仓库中的文件在添加时受版权保护。
   152  在变更文件时，请勿更新版权年份。