# Contribution Guidelines

Thank you for deciding to contribute to this project :)  
Please follow these guidelines when implementing your code.

[[_TOC_]]

## 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.

More information about the pipeline is available in the
[CI file](.gitlab-ci.yml).

## Design

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

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. |
| resources/lib/addon.py | Handles the routing and the interaction between the other modules. |
| resources/lib/peertube.py | Responsible for interacting with PeerTube. |
| resources/lib/kodi_utils.py | Provides utility functions to interact easily with Kodi. |

### main.py

The file `peertube.py` is the entry point of the add-on.

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

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

This module should 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)).

### addon.py

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.

### peertube.py

This file contains:
* the class `PeerTube` which provides simple method to send REST APIs to a
  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

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.

## Coding style

Here are the rules to follow when modifying the code:
* document the usage of functions following [Sphinx
  format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures)
* use double quotes instead of single quotes when defining strings (to avoid
  escaping apostrophes which are common characters in English and other
  languages)
* follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) conventions. The
  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
  following commands:

```python
python3 -m pip install -r misc/python_requirements.txt
python3 -m pylint --rcfile=misc/pylint-rcfile.txt
```

Note: pylint is run with python3 to have latest features even though the add-on
only supports Kodi v18 Leia (which uses python2)

## 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/))
    - the update of the change log in the `news` tag in `addon.xml` (using
      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.

## Translation

To translate the add-on you may:
* update an existing translation &rarr; 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`

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

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)).