|
| 1 | +# How to Contribute |
| 2 | + |
| 3 | +Thank you for your interest and support in tRPC! |
| 4 | + |
| 5 | +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. |
| 6 | +This document aims to provide you with a detailed contribution guide to help you better participate in the project. |
| 7 | +Please read this guide carefully before contributing and make sure to follow the rules here. |
| 8 | +We look forward to working with you to make this project better together! |
| 9 | + |
| 10 | +## Becoming a contributor |
| 11 | + |
| 12 | +The first step is registering as a tRPC-Cpp contributor. |
| 13 | +Before sending your first change to the tRPC-Cpp project you must have [signed and submitted a CLA (Contributor License Agreement)](to-do). |
| 14 | + |
| 15 | +## Before contributing code |
| 16 | + |
| 17 | +The project welcomes code patches, but to make sure things are well coordinated you should discuss any significant change before starting the work. |
| 18 | +It's recommended that you signal your intention to contribute in the issue tracker, either by claiming an [existing one](https://github.com/trpc-ecosystem/cpp-naming-etcd/issues) or by [opening a new issue](https://github.com/trpc-ecosystem/cpp-config-etcd/issues/new). |
| 19 | + |
| 20 | +### Checking the issue tracker |
| 21 | + |
| 22 | +Whether you already know what contribution to make, or you are searching for an idea, the [issue tracker](https://github.com/trpc-ecosystem/cpp-naming-etcd/issues) is always the first place to go. |
| 23 | +Issues are triaged to categorize them and manage the workflow. |
| 24 | + |
| 25 | +Most issues will be marked with one of the following workflow labels: |
| 26 | +- **NeedsInvestigation**: The issue is not fully understood and requires analysis to understand the root cause. |
| 27 | +- **NeedsDecision**: The issue is relatively well understood, but the tRPC-Cpp team hasn't yet decided the best way to address it. |
| 28 | + It would be better to wait for a decision before writing code. |
| 29 | + 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. |
| 30 | +- **NeedsFix**: The issue is fully understood and code can be written to fix it. |
| 31 | + |
| 32 | +### Opening an issue for any new problem |
| 33 | + |
| 34 | +Excluding very trivial changes, all contributions should be connected to an existing issue. |
| 35 | +Feel free to open one and discuss your plans. |
| 36 | +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. |
| 37 | +It also checks that the design is sound before code is written; the code review tool is not the place for high-level discussions. |
| 38 | + |
| 39 | +When opening an issue, make sure to answer these five questions: |
| 40 | +1. What version of tRPC-Cpp are you using ? |
| 41 | +2. What operating system and compiler are you using? |
| 42 | +3. What did you do? |
| 43 | +4. What did you expect to see? |
| 44 | +5. What did you see instead? |
| 45 | + |
| 46 | +For change proposals, see Proposing Changes To [tRPC-Proposals](to-do). |
| 47 | + |
| 48 | +## Contributing code |
| 49 | + |
| 50 | +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). |
| 51 | + |
| 52 | +Some things to keep in mind: |
| 53 | +- Ensure that your code conforms to the project's code specifications. |
| 54 | + This includes but is not limited to code style, comment specifications, etc. This helps us to maintain the cleanliness and consistency of the project. |
| 55 | +- Before submitting a PR, please make sure that you have tested your code locally(`bazel test //trpc/...`). |
| 56 | + Ensure that the code has no obvious errors and can run normally. |
| 57 | +- To update the pull request with new code, just push it to the branch; |
| 58 | + you can either add more commits, or rebase and force-push (both styles are accepted). |
| 59 | +- 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. |
| 60 | + The individual commits' descriptions will be discarded. |
| 61 | + See following "Write good commit messages" for some suggestions. |
| 62 | + |
| 63 | +### Writing good commit messages |
| 64 | + |
| 65 | +Commit messages in tRPC-Cpp follow a specific set of conventions, which we discuss in this section. |
| 66 | + |
| 67 | +Here is an example of a good one: |
| 68 | + |
| 69 | + |
| 70 | +> math: improve Sin, Cos and Tan precision for very large arguments |
| 71 | +> |
| 72 | +> The existing implementation has poor numerical properties for |
| 73 | +> large arguments, so use the McGillicutty algorithm to improve |
| 74 | +> accuracy above 1e10. |
| 75 | +> |
| 76 | +> The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm |
| 77 | +> |
| 78 | +> Fixes #159 |
| 79 | +
|
| 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-Cpp 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-Cpp. |
| 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 | + |
| 97 | +#### Referencing issues |
| 98 | + |
| 99 | +The special notation "Fixes #12345" associates the change with issue 12345 in the tRPC-Cpp issue tracker. |
| 100 | +When this change is eventually applied, the issue tracker will automatically mark the issue as fixed. |
| 101 | + |
| 102 | + |
| 103 | +## Miscellaneous topics |
| 104 | + |
| 105 | +### Copyright headers |
| 106 | + |
| 107 | +Files in the tRPC-Cpp repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date. |
| 108 | +Instead, your name will appear in the [change log](todo). |
| 109 | + |
| 110 | +New files that you contribute should use the standard copyright header: |
| 111 | + |
| 112 | +```cpp |
| 113 | +// |
| 114 | +// |
| 115 | +// Tencent is pleased to support the open source community by making tRPC available. |
| 116 | +// |
| 117 | +// Copyright (C) 2024 THL A29 Limited, a Tencent company. |
| 118 | +// All rights reserved. |
| 119 | +// |
| 120 | +// If you have downloaded a copy of the tRPC source code from Tencent, |
| 121 | +// please note that tRPC source code is licensed under the Apache 2.0 License, |
| 122 | +// A copy of the Apache 2.0 License is included in this file. |
| 123 | +// |
| 124 | +// |
| 125 | +``` |
| 126 | + |
| 127 | +Files in the repository are copyrighted the year they are added. |
| 128 | +Do not update the copyright year on files that you change. |
0 commit comments