Un add-on di Kodi per guardare contenuti ospitati su PeerTube. Riprodurre video (compresi i video in diretta) Sfoglia i video su un'istanza Cercare i video su un'istanza Selezionare l'istanza di PeerTube da utilizzare https://peertube.uno
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

172 lines
7.5 KiB

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