From d12229f5612a3aeab9e31ff757e6a8f1070a6a8b Mon Sep 17 00:00:00 2001 From: Samantaz Fox Date: Sun, 21 Apr 2024 18:07:39 +0200 Subject: [PATCH 1/4] Repo: Add CONTRIBUTING.md, remove TRANSLATION --- CONTRIBUTING.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++ TRANSLATION | 1 - 2 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md delete mode 100644 TRANSLATION diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..31e776b7 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 developper 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 +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. + +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. + +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..) + * Were you logged in? + * If the bug is caused by an external file (ex: when importing subscriptions), try to include + that too (Get in touch 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 or HMAC key first!!** + + +**Note: Security-related issues should be reported by e-mail 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 resquests + +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. + +We also accept translation updates using Pull requests, but please be aware that it represents more +work for us to merge those. + + + +## Hosting an instance + +Another way to contribute to invidious is to host a [public instance] +(https://instances.invidious.io/). + +To do so, you need a server (either a VPS or dedicated) with +[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). + +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 +other maintainers. + + + +## Testing + +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 +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. + +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 behaviot 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 developped in Crystal, a compiled language inspired from Ruby. The frontend +is developped using Crystal's own templating engine (ECR) with some vanilla JS and CSS. + +Invidious follows more or less closely the [Crystal coding convention] +(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 diff --git a/TRANSLATION b/TRANSLATION deleted file mode 100644 index fa340d71..00000000 --- a/TRANSLATION +++ /dev/null @@ -1 +0,0 @@ -https://hosted.weblate.org/projects/invidious/ From 5ab542a8d092edcf72b70580a025cd1196997901 Mon Sep 17 00:00:00 2001 From: Samantaz Fox Date: Sun, 21 Apr 2024 16:58:16 +0000 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: absidue <48293849+absidue@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31e776b7..3a29df99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ with Invidious. Here is a summary: * [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 developper and want to contribute code, or help with +* [Development](#development): You're a developer and want to contribute code, or help with reviewing the code written by others. @@ -148,7 +148,7 @@ with us on Matrix or IRC. We'll do our best to give you a better understanding o 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 behaviot you see is the expected one. After that, add a +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. From 91fdbf603350701493b332bcafe5af72ee8317f3 Mon Sep 17 00:00:00 2001 From: Samantaz Fox Date: Sun, 21 Apr 2024 21:04:05 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: TheFrenchGhosty <47571719+TheFrenchGhosty@users.noreply.github.com> Co-authored-by: Brahim Hadriche --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a29df99..f46db636 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,11 +61,11 @@ 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..) - * Were you logged in? + * Are you logged in? * If the bug is caused by an external file (ex: when importing subscriptions), try to include - that too (Get in touch with us if you want to share these files privately). + 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 or HMAC key first!!** + **Make sure to redact secrets like your DB password and HMAC key first!!** **Note: Security-related issues should be reported by e-mail at @@ -86,7 +86,7 @@ might not be as good as JavaScript-rich alternatives (like Freetube), that allow flexibility. -### Feature resquests +### Feature requests If you think that Invidious lacks some feature or another, you should open a "feature request". @@ -159,8 +159,8 @@ changes) and code snippets (for API changes) as needed. Code contributions are handled through [Github's Pull Requests (PRs)](https://github.com/iv-org/invidious/pulls). -Invidious' backend is developped in Crystal, a compiled language inspired from Ruby. The frontend -is developped using Crystal's own templating engine (ECR) with some vanilla JS and CSS. +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] (https://crystal-lang.org/reference/latest/conventions/coding_style.html#directory-and-file-names), From 69e2f37539aeb06f6ad84308dbdf0bca64d1cbe2 Mon Sep 17 00:00:00 2001 From: Samantaz Fox Date: Sun, 21 Jul 2024 18:39:59 +0200 Subject: [PATCH 4/4] Contributing: Apply suggestion from reviewers --- CONTRIBUTING.md | 115 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f46db636..074ebc39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ with Invidious. Here is a summary: 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. + 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. @@ -29,34 +29,37 @@ with Invidious. Here is a summary: 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 -with various keywords to verify that no other similar issue have already been -opened (and/or closed).** +**Note: Before opening any kind of issue, make sure to search on the tracker 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. +You can obviously use a translator if needed, but if you do, please mention it in your message, so +that we can be aware of it, and respond accordingly: nuance often gets lost in translation. 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. +Users who (understandably) do not want to use GitHub can [contact us](https://invidious.io/contact/) +with the required details. If you can write something we can directly paste into a GitHub issue that +would be perfect! + ### 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. +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 +Before anything else, **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. +caused by a configuration error on that specific instance. 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. -Here is a non-exhaustive list of details that will help us: +Otherwise, you should open a "bug report". Please include as many details as possible, so that we +can easily reproduce your problem on our side. 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 @@ -102,7 +105,7 @@ 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. +Weblate supports (Github, GitLab, etc..) for a better experience. We also accept translation updates using Pull requests, but please be aware that it represents more work for us to merge those. @@ -114,9 +117,9 @@ work for us to merge those. Another way to contribute to invidious is to host a [public instance] (https://instances.invidious.io/). -To do so, you need a server (either a VPS or dedicated) with -[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). +To do so, you need a server with [enough ressources] +(https://docs.invidious.io/installation/#hardware-requirements) to handle the load. You will also +need a domain name with a valid TLS certificate. Then, if your instance follows the [rules listed here](https://docs.invidious.io/instances/#rules-to-have-your-instance-in-this-list), @@ -125,27 +128,43 @@ you can request your instance to be added to the list by 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 -other maintainers. +keep your instance online and up to date. Finally, your instance will be added to the list. After +that We will invite you to a dedicated Matrix room for instance maintainers. + +Joining this room is not mandatory but strongly recommended, as we use it to broadcast information +about important updates, and you can also exchange with other maintainers. ## Testing -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): +New features and bug fixes must be tested before being merged. + +Once reviewed, pull requests that need to be tested will be labelled as [`need-testing`] +(https://github.com/iv-org/invidious/pulls?q=is%3Apr+is%3Aopen+label%3Aneed-testing). When one PR is +deployed on our test instance, it will be marked accordingly as [`in-testing`] +(https://github.com/iv-org/invidious/pulls?q=is%3Apr+is%3Aopen+label%3Ain-testing). + +If you have prior knowledge of Invidious, that's great, but if you don't, that's also okay! We have +a Matrix room (also bridged to IRC) that you can join to get help. We'll do our best to help you +getting started with the project. + +In general, testing these changes yourself can be achieved using the commands below (change the PR +number as required): ```bash +# Clone the repository git clone https://github.com/iv-org/invidious cd invidious -wget "https://github.com/iv-org/invidious/pull/4439.diff" -git apply 4439.diff + +# Fetch the code to a new branch (here "testing") and make it the current working tree +# Don't forget to change the PR number! +git fetch upstream pull/1234/head:testing +git checkout testing + +# Finally, run a test instance using docker 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. - 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 @@ -159,12 +178,46 @@ changes) and code snippets (for API changes) as needed. 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] +### Generalities + +#### Server side + +The server part of Invidious is developed in [Crystal](https://crystal-lang.org/), a compiled +language inspired by Ruby. The HTML templates are generated at compile time from the ECR files +present in the `src/invidious/views` folder, meaning that you need to re-compile Invidious after +changing those. + +Regarding coding style, Invidious tries to follow the [Crystal coding convention] (https://crystal-lang.org/reference/latest/conventions/coding_style.html#directory-and-file-names), -except for the "Directory and File Names" sections. +as closely as possible. Most of the rules listed here will be enforced if you run `make format`. + +We also use [Ameba](https://github.com/crystal-ameba/ameba), a static code analysis tool for Crystal. +Ameba is part of our CI/CD pipeline, but it is recommended to run it locally before pushing you +change and making a PR, like so: + +```sh +# Make sure to have all dependencies installed, including the development ones +# (this command only needs to be run once) +shards install + +# Run ameba +./bin/ameba +``` + +#### Client side + +The client side of Invidious is developped with some basic ("vanilla") JavaScript and CSS. +No complex JS framework or tooling is required (e.g NPM). + +The only dependencies Invidious has is [VideoJS](https://github.com/videojs/video.js/) plus some of +its plug-ins. VideoJS is automatically downloaded when you run `make`. + + +#### Other + +If you need to edit files the `locales/` directory, please make sure to keep the indentation as four +spaces. Any other identation will break Weblate, our translation tool (See #Translations above). ### Contributing code