From bea07f7ab2e7b272db50b6c7f4a4334f591ac6a9 Mon Sep 17 00:00:00 2001 From: Panagiotis Vasilopoulos Date: Wed, 11 Aug 2021 15:15:12 +0300 Subject: [PATCH] Update CONTRIBUTING.md Co-authored-by: Semisol Co-authored-by: Sol Fisher Romanoff Signed-off-by: Panagiotis Vasilopoulos Signed-off-by: Semisol Signed-off-by: Sol Fisher Romanoff Reference-to: https://github.com/tenacityteam/tenacity/pull/369#issuecomment-886717796 --- CONTRIBUTING.md | 180 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 148 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 910b3fe8a..045036512 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,15 +6,28 @@ have been put in place in an effort to keep the codebase clean. ## Reporting bugs and feature requests -A great place to ask questions about using Tenacity, report bugs and discuss -feature requests is the [tenacity-discuss mailing list](https://lists.sr.ht/~tenacity/tenacity-discuss). -Please search through the archives, as your question may have been asked before. -We're also available on IRC at #tenacity on Libera.Chat [(web)](https://web.libera.chat/gamja/?channels=tenacity) -if you'd like a more real-time discussion. +Our IRC channel, [`#tenacity` on Libera](https://web.libera.chat/#tenacity) +([IRC](ircs://irc.libera.chat:6697/#libera)/ +[Matrix](https://matrix.to/#/#tenacity:libera.chat)), is the best place to ask +general questions about Tenacity and talk about feature requests in real time. -The [Issues tab](https://github.com/tenacityteam/tenacity/issues) -on GitHub is restricted to **bugs and feature requests** -only. Please only submit a bug report if you are sure it is valid. +You can use [GitHub Issues](https://github.com/tenacityteam/tenacity/issues) +to report bugs and propose feature requests *only*. Support questions will be +ignored. + +The +[`tenacity-discuss` mailing list](https://lists.sr.ht/~tenacity/tenacity-discuss) +can also be used for bug reports, feature requests and discussion. +Using a mailing list is as simple as sending an ordinary email to +[`~tenacity/tenacity-discuss@lists.sr.ht`](mailto:~tenacity/tenacity-discuss@lists.sr.ht). +Keep in mind that all emails posted in our mailing list will be archived publicly. +It may be a good idea to look through our archives, because it is possible that +someone else has asked the same question as you have before. + +* Please only submit a bug report if you are sure it is valid. +* On GitHub, we use "issue templates" to help you help us. Please use them + and answer as many questions as you can. That way, we will not have to go + back and forth to understand what you want to say to us. ## Contributing @@ -25,44 +38,45 @@ requires you to Sign-off your commits, which indicates you agree to the _Note: you do not need to open a GitHub issue for every matching contribution, only for those which need further looking into, and only when asked to._ -When contributing, please adhere to the following guidelines: +### Submitting code -1. Follow proper code formatting guidelines e.g. If the file uses spaces, do not - change them to tabs. -2. Do not change any variable names unless necessary. -3. Try to keep changes compatible with upstream (Audacity) - whenever possible. -4. Make concise and accurate commit messages. A commit message should be - limited to 50 characters and its description limited to 72 characters - per line, and the message should be able to complete this sentence: +#### Sending patches through SourceHut - > This commit will... - - If you need to add any additional context, do so in the commit description. - -### Contributing through sourcehut - -SourceHut operates on an email-driven workflow, and uses [`git send-email`](https://git-send-email.io) for patch submission. Please send your -patches to +SourceHut operates on an email-driven workflow, and uses +[`git send-email`](https://git-send-email.io) for patch submission. Please send +your patches to [`~tenacity/tenacity-dev@lists.sr.ht`](mailto:~tenacity/tenacity-dev@lists.sr.ht). -When revising a patch, please use `git commit --amend` and add the `-v2` (increment every revision) -flag. -### Contributing through GitHub +When revising a patch, please use `git commit --amend` and add the `-v2` +(increment every revision) flag. + +#### Making pull requests on GitHub To contribute code using GitHub, first [fork this repository](https://github.com/tenacityteam/tenacity) and make your changes. Please use `git commit --amend` and `git push -f` for minor changes (only **your** commits). + See [git-rebase.io](https://git-rebase.io) for more details. -## Developer Certificate of Origin +### Guidelines for code + +Please adhere to the following guidelines when authoring code that you plan to submit to Tenacity: + +1. Follow proper code formatting guidelines e.g. If the file uses spaces, do not + change them to tabs. +2. Do not change any variable names unless necessary. +3. Follow the [commit message guidelines](#commit-messages). + +### Guidelines for commits + +#### Developer Certificate of Origin Tenacity is an open source project licensed under the GNU General Public license, version 2 or later (see [`LICENSE`](LICENSE.txt)). -We respect intellectual property rights, and we'd like to make sure that all -contributions are properly attributed. As such, we use the simple and clear +We respect intellectual property rights, and we would like to make sure that +all contributions are properly attributed. As such, we use the simple and clear Developer Certificate of Origin (DCO). The DCO is a declaration attached to every contribution made by every @@ -106,7 +120,7 @@ involved. Each commit must include a DCO in its description, which looks like this: ``` -Signed-off-by: Jane Doe +Signed-off-by: Con Tributor ``` You may type this line manually or, if using the command line, simply append @@ -114,3 +128,105 @@ You may type this line manually or, if using the command line, simply append We ask that all contributors use their real email address, which can be replied to. + +#### Commit messages + +The following rules continue to support hosting our code on multiple platforms, +such as both GitHub and SourceHut, without being unnecessarily locked in to +GitHub. Moreover, they are also necessary for complying to the GPL license, +ensuring our independence and just giving credit where it is due. + +Our stance on these rules is not very strict. Worst case scenario, we may +correct the commit messages for you and inform you about what we had to correct +for future reference. However, if you would like to get seriously involved +with our project and take on responsibilities such as as reviewing and merging +patches, your abidance to the following rules will also be one of the factors +that will be considered. + +Apart from including a DCO, as mentioned earlier, the following are also very +important: + +* Make concise and accurate commit messages. A commit message should be + limited to 50 characters and its description limited to 72 characters + per line, and the message should be able to complete this sentence: + + > This commit will... + + If you need to add any additional context, do so in the commit description. + +* Avoid using full stops (e.g. `.`) or past tense in your commit messages. + + - Correct: `Add support for the Commodore 64` + - Incorrect: `Added support for the Commodore 64.` + +* If you are using changes that were made by another person, make sure to + properly credit them by using the `Co-authored-by: ` tag(s) in the end of + the commit message before the `Signed-off-by:` tag(s), followed by the name + or alias that they have used in Git in the past, as well as their e-mail. + + Example: `Co-authored-by: Jane Doe ` + +* If your commit is complicated and involves multiple changes, use asterisks + and explain of the changes you made in a few words. + + Example: + + ``` + Prepare Teriyaki Sauce + + * Added Soy Sauce + * Added Cooking Sake and Sugar + * Added 1 teaspoon of Mirin + * Added Dashi Stock + * Mixed ingredients together + ``` + +* If you are using changes that were made by another person, the original + changes by that said person should generally be signed off and available + publicly in places such as another pull request on GitHub. Exceptions can + be made, but do ***not*** sign off a commit for another person without + their explicit permission. + +* If your patch resolves an issue that was previously mentioned in the Issues + tab on GitHub or in our mailing list, please use the `Reference-to:` tag, + followed by the URL where the issue in question was mentioned. + + Example: + + ``` + Reference-to: https://github.com/tenacityteam/tenacity/issues/2046 + ``` + +* Leave an empty line between tags such as `Signed-off-by:` and the rest of + the commit description. + + Example: + + ``` + Remove references to pumpkin pies + + I get that pumpkin pie is tasty, but this does not have anything to do + with Tenacity whatsoever. + + Signed-off-by: Pumpkin Hater + ``` + +##### GitHub + +* Avoid using emojis or GitHub-specific references (e.g. `:tada:`) to emojis + in your commits. They may look just fine on GitHub, but they do not anywhere + else. + +##### Maintainers + +* When merging pull requests from GitHub, make sure to remove references to + issues or pull requests that have a numeric format (e.g. `(#1234)` or + `Resolves #1234`). Please use the `Reference-to:` tag instead. + + Including a hyperlink to the said issue or pull request is preferred, because + these links will not break outside of GitHub and will also reduce confusion + between patches that refer to issues in the Audacity repository and patches + that are meant to be used in Tenacity. If you use a hyperlink instead of just + the #nnn format, GitHub will still show the #nnn format on the website, but + other websites and/or the command line will show the full hyperlink. + This is good, because it reduces our dependency on GitHub.