Browse Source

Update CONTRIBUTING.md

Co-authored-by: Semisol <hi@semisol.dev>
Co-authored-by: Sol Fisher Romanoff <sol@solfisher.com>
Signed-off-by: Panagiotis Vasilopoulos <hello@alwayslivid.com>
Signed-off-by: Semisol <hi@semisol.dev>
Signed-off-by: Sol Fisher Romanoff <sol@solfisher.com>
Reference-to: https://github.com/tenacityteam/tenacity/pull/369#issuecomment-886717796
pull/385/head
Panagiotis Vasilopoulos 10 months ago
parent
commit
bea07f7ab2
No known key found for this signature in database GPG Key ID: FD806FDB3B2C5270
  1. 182
      CONTRIBUTING.md

182
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.
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.
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.
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:
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:
> This commit will...
If you need to add any additional context, do so in the commit description.
### Submitting code
### Contributing through sourcehut
#### Sending patches 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 <j.doe@email.email>
Signed-off-by: Con Tributor <con.tributor@example.com>
```
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 <jane.doe@example.com>`
* 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 <pumpkin.hater99@example.com>
```
##### 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.
Loading…
Cancel
Save