You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

314 lines
13 KiB

  1. # Contributing to Tenacity
  2. Thanks for showing your interest to contribute, your contribution is very
  3. valuable to us as people like **you** help us build Tenacity. Some guidelines
  4. have been put in place in an effort to keep the codebase clean.
  5. ## Reporting bugs and feature requests
  6. Our IRC channel, [`#tenacity` on Libera](https://web.libera.chat/#tenacity)
  7. ([IRC](ircs://irc.libera.chat:6697/#libera)/
  8. [Matrix](https://matrix.to/#/#tenacity:libera.chat)), is the best place to ask
  9. general questions about Tenacity and talk about feature requests in real time.
  10. You can use [GitHub Issues](https://github.com/tenacityteam/tenacity/issues)
  11. to report bugs and propose feature requests *only*. Support questions will be
  12. ignored.
  13. The
  14. [`tenacity-discuss` mailing list](https://lists.sr.ht/~tenacity/tenacity-discuss)
  15. can also be used for bug reports, feature requests and discussion.
  16. Using a mailing list is as simple as sending an ordinary email to
  17. [`~tenacity/tenacity-discuss@lists.sr.ht`](mailto:~tenacity/tenacity-discuss@lists.sr.ht).
  18. Keep in mind that all emails posted in our mailing list will be archived publicly.
  19. It may be a good idea to look through our archives, because it is possible that
  20. someone else has asked the same question as you have before.
  21. * Please only submit a bug report if you are sure it is valid.
  22. * On GitHub, we use "issue templates" to help you help us. Please use them
  23. and answer as many questions as you can. That way, we will not have to go
  24. back and forth to understand what you want to say to us.
  25. ## Contributing
  26. Contributing code to Tenacity is done either via sourcehut or GitHub. Tenacity
  27. requires you to Sign-off your commits, which indicates you agree to the
  28. [Developer Certificate of Origin](#developer-certificate-of-origin). Details below.
  29. _Note: you do not need to open a GitHub issue for every matching contribution,
  30. only for those which need further looking into, and only when asked to._
  31. ### Submitting code
  32. #### Sending patches through SourceHut
  33. SourceHut operates on an email-driven workflow, and uses
  34. [`git send-email`](https://git-send-email.io) for patch submission. Please
  35. configure the repository like so:
  36. ```
  37. git config format.subjectprefix "PATCH tenacity"
  38. git config sendemail.to "~tenacity/tenacity-dev@lists.sr.ht"
  39. ```
  40. When revising a patch, please use `git commit --amend` and add the `-v2`
  41. (increment every revision) flag.
  42. #### Making pull requests on GitHub
  43. To contribute code using GitHub, first
  44. [fork this repository](https://github.com/tenacityteam/tenacity)
  45. and make your changes. Please use `git commit --amend` and
  46. `git push -f` for minor changes (only **your** commits).
  47. See [git-rebase.io](https://git-rebase.io) for more details.
  48. ### Guidelines for code
  49. Please adhere to the following guidelines when authoring code that you plan to submit to Tenacity:
  50. 1. Follow proper code formatting guidelines e.g. If the file uses spaces, do not
  51. change them to tabs.
  52. 2. Do not change any variable names unless necessary.
  53. 3. Follow the [commit message guidelines](#commit-messages).
  54. ### Guidelines for commits
  55. #### Developer Certificate of Origin
  56. Tenacity is an open source project licensed under the GNU General Public
  57. license, version 2 or later (see [`LICENSE`](LICENSE.txt)).
  58. We respect intellectual property rights, and we would like to make sure that
  59. all contributions are properly attributed. As such, we use the simple and clear
  60. Developer Certificate of Origin (DCO).
  61. The DCO is a declaration attached to every contribution made by every
  62. contributor. All the developer has to do is include a `Signed-off-by` statement,
  63. thereby agreeing to the DCO, provided below or on
  64. [developercertificate.org](https://developercertificate.org):
  65. ```
  66. Developer Certificate of Origin Version 1.1
  67. Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1
  68. Letterman Drive Suite D4700 San Francisco, CA, 94129
  69. Everyone is permitted to copy and distribute verbatim copies of this license
  70. document, but changing it is not allowed.
  71. Developer's Certificate of Origin 1.1
  72. By making a contribution to this project, I certify that:
  73. (a) The contribution was created in whole or in part by me and I have the right
  74. to submit it under the open source license indicated in the file; or
  75. (b) The contribution is based upon previous work that, to the best of my
  76. knowledge, is covered under an appropriate open source license and I have the
  77. right under that license to submit that work with modifications, whether
  78. created in whole or in part by me, under the same open source license (unless I
  79. am permitted to submit under a different license), as indicated in the file; or
  80. (c) The contribution was provided directly to me by some other person who
  81. certified (a), (b) or (c) and I have not modified it.
  82. (d) I understand and agree that this project and the contribution are public
  83. and that a record of the contribution (including all personal information I
  84. submit with it, including my sign-off) is maintained indefinitely and may be
  85. redistributed consistent with this project or the open source license(s)
  86. involved.
  87. ```
  88. Each commit must include a DCO in its description, which looks like this:
  89. ```
  90. Signed-off-by: Con Tributor <con.tributor@example.com>
  91. ```
  92. You may type this line manually or, if using the command line, simply append
  93. `-s` to your commit.
  94. We ask that all contributors use their real email address, which can be replied
  95. to.
  96. #### Commit messages
  97. The following rules continue to support hosting our code on multiple platforms,
  98. such as both GitHub and SourceHut, without being unnecessarily locked in to
  99. GitHub. Moreover, they are also necessary for complying to the GPL license,
  100. ensuring our independence and just giving credit where it is due.
  101. Our stance on these rules is not very strict. Worst case scenario, we may
  102. correct the commit messages for you and inform you about what we had to correct
  103. for future reference. However, if you would like to get seriously involved
  104. with our project and take on responsibilities such as as reviewing and merging
  105. patches, your abidance to the following rules will also be one of the factors
  106. that will be considered.
  107. Apart from including a DCO, as mentioned earlier, the following are also very
  108. important:
  109. * Make concise and accurate commit messages. A commit message should be
  110. limited to 50 characters and its description limited to 72 characters
  111. per line, and the message should be able to complete this sentence:
  112. > This commit will...
  113. If you need to add any additional context, do so in the commit description.
  114. * Avoid using full stops (e.g. `.`) or past tense in your commit messages.
  115. - Correct: `Add support for the Commodore 64`
  116. - Incorrect: `Added support for the Commodore 64.`
  117. * The first character of the commit message should be capitalized.
  118. Example:
  119. - `GH Actions: Buy celebratory Margaretha Pizza`
  120. - `Have Tenacity eat more veggies`
  121. * If you are using changes that were made by another person, make sure to
  122. properly credit them by using the `Co-authored-by: ` tag(s) in the end of
  123. the commit message before the `Signed-off-by:` tag(s), followed by the name
  124. or alias that they have used in Git in the past, as well as their e-mail.
  125. Example: `Co-authored-by: Jane Doe <jane.doe@example.com>`
  126. * If your commit is complicated and involves multiple changes, use asterisks
  127. and explain of the changes you made in a few words.
  128. Example:
  129. ```
  130. Prepare Teriyaki Sauce
  131. * Added Soy Sauce
  132. * Added Cooking Sake and Sugar
  133. * Added 1 teaspoon of Mirin
  134. * Added Dashi Stock
  135. * Mixed ingredients together
  136. ```
  137. * If you are using changes that were made by another person, the original
  138. changes by that said person should generally be signed off and available
  139. publicly in places such as another pull request on GitHub. Exceptions can
  140. be made, but do ***not*** sign off a commit for another person without
  141. their explicit permission.
  142. * If your patch resolves an issue that was previously mentioned in the Issues
  143. tab on GitHub or in our mailing list, please use the `Reference-to:` tag,
  144. followed by the URL where the issue in question was mentioned.
  145. Example:
  146. ```
  147. Reference-to: https://github.com/tenacityteam/tenacity/issues/2046
  148. ```
  149. * Leave an empty line between tags such as `Signed-off-by:` and the rest of
  150. the commit description.
  151. Example:
  152. ```
  153. Remove references to pumpkin pies
  154. I get that pumpkin pie is tasty, but this does not have anything to do
  155. with Tenacity whatsoever.
  156. Signed-off-by: Pumpkin Hater <pumpkin.hater99@example.com>
  157. ```
  158. ##### GitHub
  159. * Avoid using emojis or GitHub-specific references (e.g. `:tada:`) to emojis
  160. in your commits. They may look just fine on GitHub, but they do not anywhere
  161. else.
  162. ##### Maintainers
  163. * When merging pull requests from GitHub, make sure to remove references to
  164. issues or pull requests that have a numeric format (e.g. `(#1234)` or
  165. `Resolves #1234`). Please use the `Reference-to:` tag instead.
  166. Including a hyperlink to the said issue or pull request is preferred, because
  167. these links will not break outside of GitHub and will also reduce confusion
  168. between patches that refer to issues in the Audacity repository and patches
  169. that are meant to be used in Tenacity. If you use a hyperlink instead of just
  170. the #nnn format, GitHub will still show the #nnn format on the website, but
  171. other websites and/or the command line will show the full hyperlink.
  172. This is good, because it reduces our dependency on GitHub.
  173. ###### Merging branches
  174. * If a proposed change is running behind a certain amount of commits that affect
  175. the same "parts" of the project that the patch also affects, make sure to
  176. rebase the patch on top of the `master` branch just to be sure that the most
  177. recent changes do not cause the proposed patch to break.
  178. * In order to accommodate other reviewers that live in different timezones,
  179. the rule of thumb is to wait for up to a day before merging a change that
  180. has been approved by a reviewer, or wait around 12 hours before merging a
  181. change that has been approved by multiple people. If possible, make sure to
  182. check the change for yourself if possible, especially when a reviewer
  183. approves a change reluctantly.
  184. * Before merging any change, make sure that all (or, at the very least, *most
  185. of*) the tests have passed. If a change concerns a particular platform (e.g.
  186. macOS), then wait for the tests for that said platform to complete.
  187. * If a change affects the user interface or the audio engine, you're generally
  188. expected to use Tenacity with the included change on your machine and
  189. evaluate it. Since it's very hard to answer whether a specific change
  190. affecting the experience of the user is worth including or if the contributor
  191. should adjust their change, you may want to ask for the help of other
  192. contributors.
  193. * If there are multiple proposed changes that affect the same parts of the
  194. project, ***please wait*** for a while after initially merging a single
  195. proposed change just to be sure that this will not break the build. This does
  196. not apply to changes that do not affect the functionality of the program
  197. (such as changes to a Markdown file).
  198. The most basic way of evaluating whether two separate changes affect the same
  199. part of the project is checking whether the changes concern the same source
  200. or header files. For example, if both changes affect `src/Theme.cpp`, then
  201. they affect the same part of the project. However, this sort of evaluation
  202. can get trickier, as in large applications, different source and header files
  203. depend on each other.
  204. Rebasing patches on top of the `master` branch and making sure that they work
  205. as intended is the safest and fastest way to make sure that everything will be
  206. okay.
  207. ###### Reverting
  208. Mistakes can happen, and that's okay. After all, we're here to learn and
  209. help others. However, reverting can impose a large amount of work on yourself
  210. or other maintainers later down the line, as well as frustrate
  211. contributors -- particularly those who are contributing for the first-time
  212. or are thinking about contributing to the project.
  213. A change that breaks Tenacity should be reverted under at least some of the
  214. following conditions:
  215. * There is no obvious or fast way (up to a couple of hours) to fix the mistake
  216. that caused Tenacity to break. **Fixing is better than reverting most of the
  217. time.**
  218. * There is a high amount of activity on the project and the change that got
  219. merged is killing off that said activity.
  220. * There are maintainers and contributors that are aware of this and agree that
  221. reverting is the best cause of action.
  222. * The community appears to heavily disagree with the change.
  223. * Another person, regardless of whether they are a well-established developer
  224. or a community member, provides an additional perspective that the
  225. contributors or maintainers were not previously aware of, which calls the
  226. validity of the change into question.
  227. When reverting a change, you should be *at least* **just as careful** as when
  228. committing a change. Make sure to use your own judgement, communicate
  229. transparently and coordinate with other contributors -- especially the ones
  230. that worked on the change itself.