New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add contribution guidelines #4591
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,177 @@ | ||||||
# CONTRIBUTING | ||||||
|
||||||
## Introduction | ||||||
|
||||||
This document explains how to contribute to Invidious. | ||||||
|
||||||
Each section below describes a different way to contribute, based on your skills and experience | ||||||
with Invidious. Here is a summary: | ||||||
|
||||||
* [Issues](#issues): You are a regular user, and want to report a bug, ask for a new feature or for | ||||||
an existing feature to be improved. | ||||||
|
||||||
* [Translations](#translations): You speak English and you're fluent in another language, and want | ||||||
to help us reach more users around the globe. | ||||||
|
||||||
* [Hosting an instance](#hosting-an-instance): You're a sysadmin and have some time and server | ||||||
ressources to spare, with some prior experience with invidious. | ||||||
|
||||||
* [Testing](#testing): You're an advanced user, who is already running their own instance, is not | ||||||
worried of compiling Invidious from source, and wants to help us test bug fixes or new features. | ||||||
|
||||||
* [Development](#development): You're a developer and want to contribute code, or help with | ||||||
reviewing the code written by others. | ||||||
|
||||||
|
||||||
|
||||||
## Issues | ||||||
|
||||||
We use the [Github issue tracker](https://github.com/iv-org/invidious/issues) to track and manage | ||||||
bug reports, feature requests and improvements. | ||||||
|
||||||
**Note: Before opening any kind of issue, make sure to search on the tracker | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would even add something along the lines of "If you spot a duplicate issue, feel free to point it out" |
||||||
with various keywords to verify that no other similar issue have already been | ||||||
opened (and/or closed).** | ||||||
|
||||||
In order for everyone to be able to understand eachother, all exchanges are done in English. | ||||||
You can obviously use a translator if needed. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
Please be polite and respectful in your exchanges. Remember that we're volunteers providing that | ||||||
service for free. We don't have the time nor energy to deal with bad manners. | ||||||
|
||||||
|
||||||
### Bug reports | ||||||
|
||||||
The most common case is that you ended up on a page saying "you encountered a | ||||||
bug in Invidious" while you were browsing a channel or watching a video. | ||||||
|
||||||
In that case, you should open a "bug report". Please include as many details as possible, so | ||||||
that we can easily reproduce your problem on our side. | ||||||
|
||||||
Before opening your issue, **make sure to test a few other instances**, just to check that the | ||||||
problem you're facing is not temporary (E.g an overloaded instance, a network outage, etc.) or | ||||||
caused by configuration error on your side. | ||||||
|
||||||
If a bug report already exists for your problem, you can add a comment with more details, but make | ||||||
sure that it's useful and adds value to the discussion. If 20 people did that already, it might not | ||||||
be relevant to post a new comment. | ||||||
Comment on lines
+51
to
+57
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Move this above "you should open a "bug report" |
||||||
|
||||||
Here is a non-exhaustive list of details that will help us: | ||||||
|
||||||
* **A clear and concise list of steps to reproduce the problem** | ||||||
* A link to the page where the bug happened | ||||||
* Browser/OS version, device type (mobile, desktop, etc..) | ||||||
* Are you logged in? | ||||||
* If the bug is caused by an external file (ex: when importing subscriptions), try to include | ||||||
it too ([Get in touch](https://invidious.io/contact/) with us if you want to share these files privately). | ||||||
* If you're hosting your own instance, include relevant config file(s).\ | ||||||
**Make sure to redact secrets like your DB password and HMAC key first!!** | ||||||
|
||||||
|
||||||
**Note: Security-related issues should be reported by e-mail at | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this is fine for now but in the future we should probably be pointing this to a proper security policy at |
||||||
[security@invidious.io](mailto:security@invidious.io).** | ||||||
|
||||||
|
||||||
### Enhancement | ||||||
|
||||||
If you feel that some existing feature can be improved, you should open an "enhancement" issue. | ||||||
|
||||||
In your issue, describe what the Invidious currently does, what you don't like about it, and propose | ||||||
ways to improve that feature. If you can provide screenshots or drawings to support your explanation | ||||||
that's even better! | ||||||
|
||||||
Please be aware that Invidious is heavily aimed towards simplicity and being usable without | ||||||
Javascript. It means that we have to deal with compromises all over the place, and some features | ||||||
might not be as good as JavaScript-rich alternatives (like Freetube), that allows much more | ||||||
flexibility. | ||||||
|
||||||
|
||||||
### Feature requests | ||||||
|
||||||
If you think that Invidious lacks some feature or another, you should open a "feature request". | ||||||
|
||||||
Do note that Invidious is and will remain a Youtube-only front-end. Requests to add support for | ||||||
other services (e.g: Bandcamp, [Odyssee](https://github.com/iv-org/invidious/issues/3022)) will be | ||||||
systematically rejected. | ||||||
|
||||||
|
||||||
|
||||||
## Translations | ||||||
|
||||||
Invidious is translated in many languages using Weblate: | ||||||
https://hosted.weblate.org/projects/invidious/. | ||||||
|
||||||
We recommend creating an account or connecting with one of the other authentication providers that | ||||||
Weblate supports (Github, GitLab, Google, etc..) for a better experience. | ||||||
Comment on lines
+104
to
+105
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Isn't it mandatory to have an account? Also recommending login in via another provider is... eh There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Guest users can only do suggestions. they can't add new languages or validate suggestions, nor comment.
SSO is not a new thing... |
||||||
|
||||||
We also accept translation updates using Pull requests, but please be aware that it represents more | ||||||
work for us to merge those. | ||||||
Comment on lines
+107
to
+108
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't think we should anymore, it's really time consuming and wont "mix" with your "absolute stability"/"as little merge as possible" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. it's still much less time consuming than accepting issues and PRs by e-mail :P |
||||||
|
||||||
|
||||||
|
||||||
## Hosting an instance | ||||||
|
||||||
Another way to contribute to invidious is to host a [public instance] | ||||||
(https://instances.invidious.io/). | ||||||
SamantazFox marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
To do so, you need a server (either a VPS or dedicated) with | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Irrelevant |
||||||
[enough ressources](https://docs.invidious.io/installation/#hardware-requirements) to handle the | ||||||
load. You'll also need a domain name with a valid TLS certificate (e.g provided by Let's Encrypt). | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
ditto There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why isn't that relevant? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What an admin uses doesn't matter in this context. It's not a deployment documentation, it's just an explanation. |
||||||
|
||||||
Then, if your instance follows the | ||||||
[rules listed here](https://docs.invidious.io/instances/#rules-to-have-your-instance-in-this-list), | ||||||
you can request your instance to be added to the list by | ||||||
[creating an issue on the documentation repository](https://github.com/iv-org/documentation/issues). | ||||||
|
||||||
Once you've filled the form with your instance's informations, your instance will be added to our | ||||||
uptime monitor. From there, a probatory period of 30 days will start, to make sure that you can | ||||||
keep your instance online and up to date. Finally, your instance will be added to the list. We'll | ||||||
ask you to join our Matrix room, so that we can inform you of important updates and exchange with | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
other maintainers. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
|
||||||
|
||||||
## Testing | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it is worth mentioning the labeling system. For example if I'm in for a round of testing, I can go to PRs, filter by need-testing and have at it. Perhaps as a contributor can comment something like "I'm testing this using this scenario..." so you know which PRs are in testing There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You're right, thanks :) |
||||||
|
||||||
Once reviewed, the new features or bug fixes must be tested before being merged. In general, this | ||||||
can be achieved by running the following commands (change the PR number as required): | ||||||
```bash | ||||||
git clone https://github.com/iv-org/invidious | ||||||
cd invidious | ||||||
wget "https://github.com/iv-org/invidious/pull/4439.diff" | ||||||
git apply 4439.diff | ||||||
Comment on lines
+141
to
+142
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can be done in another way by passing the URL directly to git apply (not sure of the syntax though) Edit: found it in my notes:
using patch-diff is better by the way, pull/XXX.diff is often outdated. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The short URL ( "Patch" includes each commit separately, with message info and other overhead, where as "Diff" is the entire code change without commit information. It's pretty much the same in the end, There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The thing is that at one point pull/XX.diff was outdated but patch-diff wasn't, it's maybe solved but patch-diff was always correctly updated... so it seems safer to recommend its use. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Alternatively,
|
||||||
docker compose up | ||||||
``` | ||||||
|
||||||
If you have prior knowledge of Invidious, that's great, but otherwise feel free to get in touch | ||||||
with us on Matrix or IRC. We'll do our best to give you a better understanding of the project. | ||||||
Comment on lines
+146
to
+147
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "otherwise"? No, they should join anyway. |
||||||
|
||||||
Once you have deployed the patch on your test instance, try the changes mentionned in the pull | ||||||
request. Often times, the linked issue might contain examples of channels/comments/videos impacted. | ||||||
Definitely use those to check that the behavior you see is the expected one. After that, add a | ||||||
comment on that PR with your test methodology and your findings. Add screenshots (for interface | ||||||
changes) and code snippets (for API changes) as needed. | ||||||
|
||||||
|
||||||
|
||||||
## Development | ||||||
|
||||||
Code contributions are handled through | ||||||
[Github's Pull Requests (PRs)](https://github.com/iv-org/invidious/pulls). | ||||||
|
||||||
Invidious' backend is developed in Crystal, a compiled language inspired from Ruby. The frontend | ||||||
is developed using Crystal's own templating engine (ECR) with some vanilla JS and CSS. | ||||||
|
||||||
Invidious follows more or less closely the [Crystal coding convention] | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Badly worded |
||||||
(https://crystal-lang.org/reference/latest/conventions/coding_style.html#directory-and-file-names), | ||||||
except for the "Directory and File Names" sections. | ||||||
|
||||||
|
||||||
### Contributing code | ||||||
|
||||||
TODO | ||||||
|
||||||
|
||||||
### Reviewing code | ||||||
|
||||||
TODO |
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's something I always did.