2021-04-11 22:40:44 +02:00
|
|
|
# Contribution Guidelines
|
|
|
|
|
2021-04-11 23:51:35 +02:00
|
|
|
Thank you for deciding to contribute to this project :)
|
2021-04-11 22:40:44 +02:00
|
|
|
Please follow these guidelines when implementing your code.
|
|
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
2021-04-11 23:51:35 +02:00
|
|
|
## Change workflow
|
|
|
|
|
|
|
|
The `main` branch contains the latest version of the code. This branch must be
|
|
|
|
stable and working at any time. To ensure this CI pipelines are used.
|
|
|
|
|
|
|
|
The workflow is the following:
|
|
|
|
1. create a branch on the main repository with an explicit name
|
|
|
|
1. create a merge request from your branch against the `main` branch
|
|
|
|
1. a pipeline is created each time you push commits in a merge request but it
|
|
|
|
will not start automatically: the user may start it. Since a merge request
|
|
|
|
cannot be merged until the associated pipeline passed, start the `blocked
|
|
|
|
pipeline` associated with the latest commit in your merge request when your
|
|
|
|
change is ready.
|
|
|
|
1. if the pipeline passed, the merge request may be merged by one of the
|
|
|
|
maintainers. Note that the preferred option is to squash commits.
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
More information about the pipeline is available in the
|
2021-04-11 23:51:35 +02:00
|
|
|
[CI file](.gitlab-ci.yml).
|
|
|
|
|
2021-04-19 15:04:57 +02:00
|
|
|
## Design
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
Basically the add-on is composed of:
|
|
|
|
* a service which will download the torrent videos in the background
|
|
|
|
* classes which will retrieved information and play videos from a PeerTube
|
|
|
|
instance
|
|
|
|
|
2021-04-19 15:04:57 +02:00
|
|
|
The add-on is based on the following python modules:
|
|
|
|
|
|
|
|
| Name | Description |
|
|
|
|
| ------ | ------ |
|
|
|
|
| main.py | Entry point of the add-on. |
|
|
|
|
| service.py | Service responsible for downloading torrent files in the background. |
|
2021-04-22 22:48:20 +02:00
|
|
|
| resources/lib/addon.py | Handles the routing and the interaction between the other modules. |
|
2021-04-19 15:04:57 +02:00
|
|
|
| resources/lib/peertube.py | Responsible for interacting with PeerTube. |
|
|
|
|
| resources/lib/kodi_utils.py | Provides utility functions to interact easily with Kodi. |
|
|
|
|
|
|
|
|
### main.py
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
The file `peertube.py` is the entry point of the add-on.
|
2021-04-19 15:04:57 +02:00
|
|
|
|
|
|
|
This module must be as short as possible (15 effective lines of code maximum)
|
|
|
|
to comply with Kodi add-on development best practices (checked by the
|
|
|
|
[Kodi add-on checker](https://github.com/xbmc/addon-check)).
|
|
|
|
|
|
|
|
### service.py
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
Note: the design of this module is still based on the alpha version.
|
|
|
|
|
|
|
|
It contains 2 classes:
|
|
|
|
* PeertubeService: code of the service which is run by Kodi. It will
|
|
|
|
instantiate `PeertubeDownloader` when the signal to start a download is
|
|
|
|
received from `addon.py`
|
|
|
|
* PeertubeDownloader: downloads torrent in an independent thread
|
2021-04-19 15:04:57 +02:00
|
|
|
|
2021-04-27 22:52:59 +02:00
|
|
|
This module should be as short as possible (15 effective lines of code maximum)
|
2021-04-19 15:04:57 +02:00
|
|
|
to comply with Kodi add-on development best practices (checked by the
|
|
|
|
[Kodi add-on checker](https://github.com/xbmc/addon-check)).
|
|
|
|
|
|
|
|
### addon.py
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
This module contains the class `PeerTubeAddon` which is the main class of the
|
|
|
|
add-on. It is responsible for calling the other modules and classes to provide
|
|
|
|
the features of the add-on.
|
2021-04-19 15:04:57 +02:00
|
|
|
|
|
|
|
### peertube.py
|
|
|
|
|
|
|
|
This file contains:
|
2021-04-22 22:48:20 +02:00
|
|
|
* the class `PeerTube` which provides simple method to send REST APIs to a
|
2021-04-19 15:04:57 +02:00
|
|
|
PeerTube instance
|
|
|
|
* the function `list_instances` which lists the PeerTube instances from
|
|
|
|
joinpeertube.org. The URL of the API used by this function and the structure
|
|
|
|
of the response in case of errors is different than the other PeerTube APIs
|
|
|
|
(which are sent to a specific instance) so it made sense to have it as a
|
|
|
|
dedicated function. If more instance-related API are used in the future, a
|
|
|
|
class could be created.
|
|
|
|
|
|
|
|
### kodi_utils.py
|
|
|
|
|
2021-04-22 22:48:20 +02:00
|
|
|
This module contains the class `KodiUtils` which provides utility methods
|
|
|
|
to the other modules so that the Kodi APIs can be called easily. It imports the
|
|
|
|
xbmc file and the other modules should not import any xmbc file.
|
|
|
|
|
|
|
|
A global instance of the class `KodiUtils` which is called `kodi` is defined in
|
|
|
|
this file so that it can be reused easily anywhere in the add-on by simply
|
|
|
|
importing this module.
|
|
|
|
|
|
|
|
Some important features provided by this module:
|
|
|
|
* The methods `get_property` and `set_property` allows to manage data which
|
|
|
|
will remain available when the current call of the add-on ends. It can also
|
|
|
|
be used to share information between the service and the rest of the add-on.
|
|
|
|
* There are some helper functions which make the creation of items in Kodi UI
|
|
|
|
easier.
|
|
|
|
`generate_item_info` creates a dict with the required information to create
|
|
|
|
an item: it allows to define only the parameters that are useful for a given
|
|
|
|
items and the method will use a correct value for the other parameters.
|
|
|
|
Then `create_items_in_ui` is called with the information generated by
|
|
|
|
`generate_item_info` to actually create the items in the UI.
|
2021-04-19 15:04:57 +02:00
|
|
|
|
2021-04-11 22:40:44 +02:00
|
|
|
## Coding style
|
|
|
|
|
2021-04-19 15:20:47 +02:00
|
|
|
Here are the rules to follow when modifying the code:
|
2021-04-11 23:51:35 +02:00
|
|
|
* document the usage of functions following [Sphinx
|
|
|
|
format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures)
|
2021-04-19 15:20:47 +02:00
|
|
|
* use double quotes instead of single quotes when defining strings (to avoid
|
|
|
|
escaping apostrophes which are common characters in English and other
|
|
|
|
languages)
|
2021-04-11 23:51:35 +02:00
|
|
|
* follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) conventions. The
|
2021-04-19 15:20:47 +02:00
|
|
|
compliance is checked in the `quality` job (more details are available in the
|
|
|
|
[CI file](.gitlab-ci.yml)). Pylint can also be run locally with the
|
2021-04-11 23:51:35 +02:00
|
|
|
following commands:
|
|
|
|
|
|
|
|
```python
|
|
|
|
python3 -m pip install -r misc/python_requirements.txt
|
|
|
|
python3 -m pylint --rcfile=misc/pylint-rcfile.txt
|
|
|
|
```
|
|
|
|
|
2021-04-19 15:20:47 +02:00
|
|
|
Note: pylint is run with python3 to have latest features even though the add-on
|
2021-04-11 23:51:35 +02:00
|
|
|
only supports Kodi v18 Leia (which uses python2)
|
2021-04-11 22:40:44 +02:00
|
|
|
|
|
|
|
## How to release a new version of this add-on
|
|
|
|
|
|
|
|
These steps should be followed only by maintainers.
|
|
|
|
|
|
|
|
1. Create a release branch whose name follows this format:
|
|
|
|
`release/<release_name>`
|
|
|
|
2. On this branch don't commit any new feature. Only commit changes related to
|
|
|
|
the release process like:
|
|
|
|
- a bump of the add-on version in `addon.xml` (note that the version
|
|
|
|
numbering must follow the [semantic versioning](https://semver.org/))
|
2021-04-22 22:48:20 +02:00
|
|
|
- the update of the change log in the `news` tag in `addon.xml` (using
|
2021-04-11 22:40:44 +02:00
|
|
|
Markdown syntax since it will be re-used automatically in the release
|
|
|
|
notes)
|
|
|
|
3. Merge the merge request (maintainers only)
|
|
|
|
4. A new pipeline with the job `create-release` will be created: run the job
|
|
|
|
manually since it should be `blocked` (maintainers only)
|
|
|
|
5. The new release will be available on the releases page.
|
2021-04-27 22:52:59 +02:00
|
|
|
|
|
|
|
## Translation
|
|
|
|
|
|
|
|
To translate the add-on you may:
|
2021-04-30 18:35:20 +02:00
|
|
|
* update an existing translation → edit the corresponding
|
|
|
|
`strings.po` file in the folder of `resources/language/resource.language.<lang>`
|
|
|
|
* translate the add-on into a new language:
|
|
|
|
* create a new `strings.po` file for your language in
|
|
|
|
`resources/language/resource.language.<lang>`
|
|
|
|
* translate the `summary`, `description` and `disclaimer` tags in the file
|
|
|
|
`addon.xml`
|
2021-04-27 22:52:59 +02:00
|
|
|
|
2021-04-29 22:38:14 +02:00
|
|
|
More information about the translation system used by Kodi and its add-ons is
|
|
|
|
available [here](https://kodi.wiki/view/Language_support).
|
|
|
|
|
|
|
|
While translating please take care to:
|
|
|
|
* Keep the `{}`: they will be replaced by variables in the code
|
|
|
|
* Keep the punctuation but adapt it to your language's rules (for instance the
|
|
|
|
number of spaces around `:` varies from one language to another)
|
|
|
|
* Translate using the meaning of the original string but try to not exceed too
|
|
|
|
much the length of the original string (otherwise it may have a negative
|
|
|
|
impact on the user experience e.g. with overlapping strings)
|
|
|
|
* If you hesitate between several translations for a "technical" word, try to
|
|
|
|
use the translation of this word from the Kodi interface
|
|
|
|
|
2021-04-27 22:52:59 +02:00
|
|
|
A CI job called `translation` is available in each merge request which contains
|
|
|
|
changes in strings.po files. It checks that the reference strings in the
|
|
|
|
translation files are the same as in the reference file
|
|
|
|
([resources/language/resource.language.en_gb/strings.po](./resources/language/resource.language.en_gb/strings.po)).
|