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

     1  English | [中文](CONTRIBUTING.zh_CN.md)
     2  
     3  # How to Contribute
     4  
     5  Thank you for your interest and support in tRPC!
     6  
     7  We welcome and appreciate any form of contribution, including but not limited to submitting issues, providing improvement suggestions, improving documentation, fixing bugs, and adding features.
     8  This document aims to provide you with a detailed contribution guide to help you better participate in the project.
     9  Please read this guide carefully before contributing and make sure to follow the rules here.
    10  We look forward to working with you to make this project better together!
    11  
    12  ## Before contributing code
    13  
    14  The project welcomes code patches, but to make sure things are well coordinated you should discuss any significant change before starting the work.
    15  It's recommended that you signal your intention to contribute in the issue tracker, either by claiming an [existing one](https://github.com/trpc-group/trpc-go/issues) or by [opening a new issue](https://github.com/trpc-group/trpc-go/issues/new).
    16  
    17  ### Checking the issue tracker
    18  
    19  Whether you already know what contribution to make, or you are searching for an idea, the [issue tracker](https://github.com/trpc-group/trpc-go/issues) is always the first place to go.
    20  Issues are triaged to categorize them and manage the workflow.
    21  
    22  Most issues will be marked with one of the following workflow labels:
    23  - **NeedsInvestigation**: The issue is not fully understood and requires analysis to understand the root cause.
    24  - **NeedsDecision**: The issue is relatively well understood, but the tRPC-Go team hasn't yet decided the best way to address it.
    25    It would be better to wait for a decision before writing code.
    26    If you are interested in working on an issue in this state, feel free to "ping" maintainers in the issue's comments if some time has passed without a decision.
    27  - **NeedsFix**: The issue is fully understood and code can be written to fix it.
    28  
    29  ### Opening an issue for any new problem
    30  
    31  Excluding very trivial changes, all contributions should be connected to an existing issue.
    32  Feel free to open one and discuss your plans.
    33  This process gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside the goals for the language and tools.
    34  It also checks that the design is sound before code is written; the code review tool is not the place for high-level discussions.
    35  
    36  When opening an issue, make sure to answer these five questions:
    37  1. What version of tRPC-Go are you using ?
    38  2. What operating system and processor architecture are you using(`go env`)?
    39  3. What did you do?
    40  4. What did you expect to see?
    41  5. What did you see instead?
    42  
    43  For change proposals, see Proposing Changes To [tRPC-Proposals](https://github.com/trpc-group/trpc/tree/main/proposal).
    44  
    45  ## Contributing code
    46  
    47  Follow the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) to [create a GitHub pull request](https://docs.github.com/en/get-started/quickstart/github-flow#create-a-pull-request).
    48  If this is your first time submitting a PR to the tRPC-Go project, you will be reminded in the "Conversation" tab of the PR to sign and submit the [Contributor License Agreement](https://github.com/trpc-group/cla-database/blob/main/Tencent-Contributor-License-Agreement.md).
    49  Only when you have signed the Contributor License Agreement, your submitted PR has the possibility of being accepted.
    50  
    51  Some things to keep in mind:
    52  - Ensure that your code conforms to the project's code specifications.
    53    This includes but is not limited to code style, comment specifications, etc. This helps us to maintain the cleanliness and consistency of the project.
    54  - Before submitting a PR, please make sure that you have tested your code locally(`go test ./...`).
    55    Ensure that the code has no obvious errors and can run normally.
    56  - To update the pull request with new code, just push it to the branch;
    57    you can either add more commits, or rebase and force-push (both styles are accepted).
    58  - If the request is accepted, all commits will be squashed, and the final commit description will be composed by concatenating the pull request's title and description.
    59    The individual commits' descriptions will be discarded.
    60    See following "Write good commit messages" for some suggestions.
    61  
    62  ### Writing good commit messages
    63  
    64  Commit messages in tRPC-Go follow a specific set of conventions, which we discuss in this section.
    65  
    66  Here is an example of a good one:
    67  
    68  
    69  > math: improve Sin, Cos and Tan precision for very large arguments
    70  >
    71  > The existing implementation has poor numerical properties for
    72  > large arguments, so use the McGillicutty algorithm to improve
    73  > accuracy above 1e10.
    74  >
    75  > The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
    76  >
    77  > Fixes #159
    78  >
    79  > RELEASE NOTES: Improved precision of Sin, Cos, and Tan for very large arguments (>1e10) 
    80  
    81  #### First line
    82  
    83  The first line of the change description is conventionally a short one-line summary of the change, prefixed by the primary affected package.
    84  
    85  A rule of thumb is that it should be written so to complete the sentence "This change modifies tRPC-Go to _____."
    86  That means it does not start with a capital letter, is not a complete sentence, and actually summarizes the result of the change.
    87  
    88  Follow the first line by a blank line.
    89  
    90  #### Main content
    91  
    92  The rest of the description elaborates and should provide context for the change and explain what it does.
    93  Write in complete sentences with correct punctuation, just like for your comments in tRPC-Go.
    94  Don't use HTML, Markdown, or any other markup language.
    95  Add any relevant information, such as benchmark data if the change affects performance.
    96  The [benchstat](https://godoc.org/golang.org/x/perf/cmd/benchstat) tool is conventionally used to format benchmark data for change descriptions.
    97  
    98  #### Referencing issues
    99  
   100  The special notation "Fixes #12345" associates the change with issue 12345 in the tRPC-Go issue tracker.
   101  When this change is eventually applied, the issue tracker will automatically mark the issue as fixed.
   102  
   103  - If there is a corresponding issue, add either `Fixes #12345` or `Updates #12345` (the latter if this is not a complete fix) to this comment
   104  - If referring to a repo other than `trpc-go` you can use the `owner/repo#issue_number` syntax: `Fixes trpc-group/tnet#12345`
   105  
   106  #### PR type label
   107  
   108  The PR type label is used to help identify the types of changes going into the release over time. This may allow the Release Team to develop a better understanding of what sorts of issues we would miss with a faster release cadence.
   109  
   110  For all pull requests, one of the following PR type labels must be set:
   111  
   112  - type/bug: Fixes a newly discovered bug.
   113  - type/enhancement: Adding tests, refactoring.
   114  - type/feature: New functionality.
   115  - type/documentation: Adds documentation.
   116  - type/api-change: Adds, removes, or changes an API.
   117  - type/failing-test: CI test case is showing intermittent failures.
   118  - type/performance: Changes that improves performance.
   119  - type/ci: Changes the CI configuration files and scripts.
   120  
   121  #### Release notes
   122  
   123  Release notes are required for any pull request with user-visible changes, this could mean:
   124  
   125  - User facing, critical bug-fixes
   126  - Notable feature additions
   127  - Deprecations or removals
   128  - API changes
   129  - Documents additions
   130  
   131  If the current PR doesn't have user-visible changes, such as internal code refactoring or adding test cases, the release notes should be filled with 'NONE' and the changes in this PR will not be recorded in the next version's CHANGELOG. If the current PR has user-visible changes, the release notes should be filled out according to the actual situation, avoiding technical details and describing the impact of the current changes from a user's perspective as much as possible.
   132  
   133  Release notes are one of the most important reference points for users about to import or upgrade to a particular release of tRPC-Go.
   134  
   135  ## Miscellaneous topics
   136  
   137  ### Copyright headers
   138  
   139  Files in the tRPC-Go repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date.
   140  Instead, your name will appear in the change log.
   141  
   142  New files that you contribute should use the standard copyright header:
   143  
   144  ```go
   145  //
   146  //
   147  // Tencent is pleased to support the open source community by making tRPC available.
   148  //
   149  // Copyright (C) 2023 THL A29 Limited, a Tencent company.
   150  // All rights reserved.
   151  //
   152  // If you have downloaded a copy of the tRPC source code from Tencent,
   153  // please note that tRPC source code is licensed under the  Apache 2.0 License,
   154  // A copy of the Apache 2.0 License is included in this file.
   155  //
   156  //
   157  ```
   158  
   159  Files in the repository are copyrighted the year they are added.
   160  Do not update the copyright year on files that you change.