Browse Source

Improve contribution guidelines (#772)

* Update issue template

* Add a known issues file

* Rewrite the contribution guidelines
pull/807/head
Sebastian Meyer 5 years ago
committed by Forrest
parent
commit
b2b6f595a8
  1. 102
      CONTRIBUTING.md
  2. 15
      ISSUE_TEMPLATE.md
  3. 4
      KNOWN_ISSUES.md

102
CONTRIBUTING.md

@ -1,3 +1,99 @@
Thank you for helping the Streamlink project! Before opening a new ticket,
please make sure that there's no similar ticket already opened for your
issue and that it isn't a [known issue](https://streamlink.github.io/players.html#known-issues-and-workarounds).
# Contributing to Streamlink
Want to get involved? Thanks! There are plenty of ways to help!
## Reporting issues
A bug is a *demonstrable problem* that is caused by the **latest version** of the code in the repository. Good bug reports are extremely helpful - thank you!
Please read the following guidelines before you [report an issue][issues]:
1. **See if the issue is already known** — check the list of [known issues][known-issues].
2. **Use the GitHub issue search** — check if the issue has already been reported. If it has been, please comment on the existing issue.
3. **Check if the issue has been fixed** — the latest `master` or development branch may already contain a fix.
4. **Isolate the demonstrable problem** — make sure that the code in the project's repository is *definitely* responsible for the issue.
5. **Format your issue report** — [well formatted texts][mastering-markdown] will make it much easier for developers to understand your report.
Please try to be as detailed as possible in your report too. What is your environment? What steps will reproduce the issue? What would you expect the outcome to be? All these details will help people to assess and fix any potential bugs. The [issue template][issue-template] will aid you in structuring your report when submitting a new issue. If your report includes log output, please provide it as text in multi-line code blocks if possible for better readability. Thank you!
## Feature requests
Feature requests are welcome, but take a moment to find out whether your idea fits with the scope and aims of the project. It's up to *you* to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible.
## Plugin requests
Plugin submissions and requests are a great way to improve Streamlink. Requests should be as detailed as possible and dedicated to only a single streaming service. Information about the service as well as explicit URLs for live streams or recordings are encouraged so that the requested plugin can be easily implemented. Please be aware that plugins for streaming services that are using DRM protections will not be implemented.
## Pull requests
Good pull requests - patches, improvements, and new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
**Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.
Please adhere to the coding conventions used throughout a project (indentation, white space, accurate comments, etc.) and any other requirements (such as test coverage).
Adhering to the following process is the best way to get your work included in the project:
1. [Fork][howto-fork] the project, clone your fork, and configure the remotes:
```bash
# Clone your fork of the repo into the current directory
git clone git@github.com:<YOUR-USERNAME>/streamlink.git
# Navigate to the newly cloned directory
cd streamlink
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/streamlink/streamlink.git
```
2. If you cloned a while ago, get the latest changes from upstream
```bash
git checkout master
git pull upstream master
```
3. Create a new topic branch (off the main project branch) to contain your feature, change, or fix:
```bash
git checkout -b <TOPIC-BRANCH-NAME>
```
4. Commit your changes in logical chunks. Please adhere to these [git commit message guidelines][howto-format-commits] or your code is unlikely be merged into the project. Use git's [interactive rebase][howto-rebase] feature to tidy up your commits before making them public.
5. Locally merge (or rebase) the upstream branch into your topic branch:
```bash
git pull [--rebase] upstream master
```
6. Push your topic branch up to your fork:
```bash
git push origin <TOPIC-BRANCH-NAME>
```
7. [Open a Pull Request][howto-open-pull-requests] with a clear title and description.
**IMPORTANT**: By submitting a patch, you agree to allow the project owners to license your work
under the terms of the [BSD 2-clause license][license].
## Acknowledgements
This contributing guide has been adapted from [HTML5 boilerplate's guide][ref-h5bp].
[issues]: https://github.com/streamlink/streamlink/issues
[known-issues]: https://github.com/streamlink/streamlink/blob/master/KNOWN_ISSUES.md
[issue-template]: https://github.com/streamlink/streamlink/blob/master/ISSUE_TEMPLATE.md
[mastering-markdown]: https://guides.github.com/features/mastering-markdown
[howto-fork]: https://help.github.com/articles/fork-a-repo
[howto-rebase]: https://help.github.com/articles/interactive-rebase
[howto-format-commits]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[howto-open-pull-requests]: https://help.github.com/articles/using-pull-requests
[Git]: https://git-scm.com
[license]: https://github.com/streamlink/streamlink/blob/master/LICENSE
[ref-h5bp]: https://github.com/h5bp/html5-boilerplate/blob/master/CONTRIBUTING.md

15
ISSUE_TEMPLATE.md

@ -1,7 +1,9 @@
*Thanks for reporting an issue!*
*Please read the contribution guidelines first!*
*Please read the contribution guidelines first! (see the link above)*
*Also check the list of known issues before reporting an issue!*
*Feel free to use the following template. Be as detailed as possible.*
*Please see the text preview to avoid unnecessary formatting errors.*
*Don't forget to remove this text before submitting.*
----
@ -9,9 +11,9 @@
### Checklist
- [x] This is a bug report.
- [ ] This is a plugin request.
- [ ] This is a feature request.
- [ ] I used the search function to find already opened/closed issues or pull requests.
- [ ] This is a plugin (improvement) request.
- [ ] I have read the contribution guidelines.
### Description
@ -21,13 +23,16 @@
...
### Reproduction steps / Stream URLs to test
### Reproduction steps / Explicit stream URLs to test
1. ...
2. ...
3. ...
### Environment details (operating system, python version, etc.)
### Environment details
Operating system and version: ...
Streamlink and Python version: ...
...

4
KNOWN_ISSUES.md

@ -0,0 +1,4 @@
# Known issues
For a detailed list of known issues, see here:
https://streamlink.github.io/players.html#known-issues-and-workarounds
Loading…
Cancel
Save