Skip to content

Latest commit

 

History

History
152 lines (110 loc) · 7.48 KB

CONTRIBUTING.zh_CN.md

File metadata and controls

152 lines (110 loc) · 7.48 KB
Raw

English | 中文

如何贡献

感谢您对 tRPC-Go 的关注和支持！

我们欢迎并感激任何形式的贡献，包括但不限于提交 issue、提供改进建议、改进文档、修复错误和添加功能。 本文档旨在为您提供详细的贡献指南，以帮助您更好地参与项目。 在贡献之前，请仔细阅读本指南并确保遵循这里的规则。 我们期待与您共同努力，使这个项目变得更好！

在贡献代码之前

项目欢迎代码补丁，但为了确保事情得到良好协调，您应该在开始工作之前讨论任何重大变更。 建议您在 issue 跟踪器中表明您的贡献意图，可以通过认领现有 issue或创建新 issue 来实现。

查看 issue 跟踪器

无论您已经知道要做哪些贡献，还是正在寻找想法，issue 跟踪器始终是您的第一个去处。 issue 会被分类以管理工作流程。

大多数 issue 都会被标记为以下工作流标签之一：

  • NeedsInvestigation：issue 尚未完全理解，需要分析以了解根本原因。
  • NeedsDecision：issue 相对已经理解得很好，但 tRPC-Go 团队尚未决定解决 issue 的最佳方法。 在编写代码之前最好等待决策。 如果一段时间内没有决策且您有兴趣处理处于这种状态的 issue，请随时在 issue 评论中“ping”维护者。
  • NeedsFix：issue 已完全理解，可以编写代码进行修复。

为任何新问题打开一个 issue

除非是非常细小的变更，否则所有贡献都应与现有 issue 有关。 请随时打开一个 issue 并讨论您的计划。 这个过程让每个人都有机会验证设计，有助于防止工作重复，确保想法符合语言和工具的目标。 在编写代码之前，还可以检查设计是否合理；代码审查工具并非用于高层次的讨论。

在提交 issue 时，请确保回答以下五个问题：

  1. 您正在使用哪个版本的tRPC-Go？
  2. 您正在使用哪个操作系统和处理器架构（go env）？
  3. 您做了什么？
  4. 您期望看到什么？
  5. 您实际看到的是什么？

关于变更提案，请参阅向 tRPC-Proposals 提议变更。

贡献代码

遵循 GitHub 流程来创建 GitHub PR(Pull Request)。

如果你是第一次向 tRPC-Go 项目提交 PR，那么在该 PR 的对话栏中会提醒你签署并提交贡献者许可协议。 只有当你签署过贡献者许可协议，你提交的 PR 才有可能被接受。 请记住以下几点：

  • 确保您的代码符合项目的代码规范。 这包括但不限于代码风格、注释规范等。这有助于我们维护项目的整洁性和一致性。
  • 在提交 PR 之前，请确保您已在本地测试过您的代码。 确保代码没有明显的错误并且可以正常运行。
  • 要使用新代码更新拉取请求，只需将其推送到分支； 您可以添加更多提交，也可以 rebase 并 force-push（两种风格都可以接受）。
  • 如果请求被接受，所有提交将被压缩，最终提交描述将由 PR 的标题和描述组成。 单个提交的描述将被丢弃。 请参阅以下“编写良好的提交消息”以获取一些建议。

编写良好的提交消息

tRPC-Go 中的提交消息遵循一套特定的约定，我们将在本节中讨论。

以下是一个良好的示例：

math: improve Sin, Cos and Tan precision for very large arguments

The existing implementation has poor numerical properties for large arguments, so use the McGillicutty algorithm to improve accuracy above 1e10.

The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm

Fixes #159

RELEASE NOTES: Improved precision of Sin, Cos, and Tan for very large arguments (>1e10)

第一行

变更描述的第一行通常是一个简短的一行摘要，描述变更的内容，并以主要受影响的包为前缀。

一个经验法则是，它应该被写成完成句子 "This change modifies tRPC-Go to _____." 这意味着它不以大写字母开头，不是一个完整的句子，而且确实概括了变更的结果。

在第一行之后空一行。

主要内容

描述的其余部分应该详细说明，为变更提供上下文并解释它的作用。 像在 tRPC-Go 中的注释一样，使用正确的标点符号写完整的句子。 不要使用 HTML、Markdown 或任何其他标记语言。 添加任何相关信息，例如如果变更影响性能，请添加基准数据。 benchstat工具通常用于为变更描述格式化基准数据。

引用 issue

特殊表示法 "Fixes #12345" 将变更与 tRPC-Go issue 跟踪器中的 issue 12345关联。 当此变更最终应用时，issue 跟踪器将自动将该 issue 标记为已修复。

  • 如果有相关 issue，请在此评论中添加 Fixes #12345 或 Updates #12345（如果这不是完整的修复）
  • 如果涉及到的仓库不是 trpc-go，则可以使用 owner/repo#issue_number 语法：Fixes trpc-group/tnet#12345

PR 类型标签

PR 类型标签用于标识当前 PR 变更所属的类型，为后续发布版本提供参考。这有助于发布团队在更快的发布周期里，准确识别当前周期内所有类型的问题。

对于所有 PR，必须设置以下之一的 PR 类型标签：

  • type/bug: 修复新发现的 bug。
  • type/enhancement: 添加测试，重构内部代码。
  • type/feature: 新功能。
  • type/documentation: 添加文档。
  • type/api-change: 添加、删除或更改 API。
  • type/failing-test: CI 测试用例偶发失败。
  • type/performance: 改进性能的变更。
  • type/ci: 更改 CI 配置文件和脚本。

发布说明

对于任何造成用户可见更改的 PR，都需要提供发布说明。这可能包括：

  • 用户可见的关键 bug 修复
  • 显著的功能增加
  • 功能弃用或移除
  • API 更改
  • 文档添加

如果当前 PR 没有用户可见的变更，例如代码内部重构，添加测试用例等情况，发布说明内容填为 'NONE'，这个 PR 的变更就不会记录在下个版本的 CHANGELOG 中；如果当前 PR 有用户可见的变更，发布说明内容需要按照实际情况填写，尽量不要涉及技术细节，在用户视角描述当前变更会造成的影响。

发布说明是用户即将使用或升级到 tRPC-Go 特定版本时的最重要参考点之一。

其他主题

版权声明

tRPC-Go 代码仓库中的文件不列出作者姓名，以避免混乱并避免不断更新列表。 而您的名字将出现在变更日志中。

您贡献的新文件应使用标准版权声明：

//
//
// Tencent is pleased to support the open source community by making tRPC available.
//
// Copyright (C) 2023 THL A29 Limited, a Tencent company.
// All rights reserved.
//
// If you have downloaded a copy of the tRPC source code from Tencent,
// please note that tRPC source code is licensed under the  Apache 2.0 License,
// A copy of the Apache 2.0 License is included in this file.
//
//

代码仓库中的文件在添加时受版权保护。 在变更文件时，请勿更新版权年份。