Submitting Add-ons: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
(Don't allow new addons into Leia anymore, only updates to existing addons.)
 
(44 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{mininav|[[Development]]|[[Add-on development]]}}
{{mininav|[[Development]]|[[Add-on development]]}}


== Repository Submission Guidelines - Please Read Before Submitting Your Addon ==
Because maintaining such a large repository is a large task, we have set some guidelines for inclusion. Please ensure that these guidelines are met before submitting request to be added.
In order to be considered for the official repository, the following guidelines must be met:
* All add-ons must be developed as described on the [[Add-on development]] page.
* You ''must'' include a license file (named LICENSE.txt). We recommend the [http://creativecommons.org/choose/non-web-popup?license_code=by-sa&jurisdiction=&version=3.0&lang=en CC-BY-SA 3.0] for skins and the [http://www.gnu.org/licenses/gpl-howto.html GPL v2+] for others, but most copyleft licenses will suffice.
* All files must be free and legal to distribute.
* The add-on must not violate any known copyright laws - if in doubt, let us know and we'll look into it for you.
* All source files must be included. No pre-compiled files or skins will be allowed.
* You acknowledge that you are the maintainer of your addon, but the XBMC team reserves the right to update or remove it at any time as we deem necessary.
* If a new stable XBMC is going to be released no new submissions are accepted to the repository for the previous version. This will start from when the first [http://en.wikipedia.org/wiki/Release_candidate#Release_candidate release candidate (RC)] of the new version is released. Only fixes and updates will be accepted and processed for the previous version (e.g. if the current stable is 12.0 no updates are allowed for 10.1 any more).
* Add-ons that contain advertising will not be allowed


=== Updates ===
Keep in mind that add-ons in the official repository should be considered ''stable''. This means that they should be well-tested before you submit them for inclusion.
Because they are for stable users, they should avoid being updated too often. If your add-on is in rapid development, and features are constantly being added, hold off until you have hit a good stopping point and ''tested'' the current version.


This means that you should ''not'' submit a request every time you change your code. If you are submitting updates more than once per week something is wrong. Once per month is probably a better goal, barring unforeseen conditions (like a content source changing its paths).
=== Submitting a Compliant Add-on to the Kodi.tv Repo ===


=== General requirements ===
After you have read the [[Add-on rules|repository guidelines]] and made sure your addon is compliant with them, you may begin the submission process using the following steps.


* All strings used by add-ons must be localized, no hard-coded language strings should ever be used
=== Allowed submissions ===
* All paths should be treated as case-sensitive, so that they work on all OSs and filesystems.
* All paths and files should be lower-case due to the previous point (except for README / COPYING / LICENSE.txt that should be upper-case).
* The following file-types are not allowed: .so .dll .pyo .exe .xbt .xpr Thumbs.db <binary files>
* All text files should use UNIX end-of-line


=== Requirements for skins ===
We have restricted the allowed submissions of add-ons to past Kodi versions.
* The file size must be sane. There is no hard limit, but a 100mb skin is pushing it.
Several reasons:
* No mods. Mods are great, and pop up frequently in the forums. But they are only confusing to non-forum-goers. This can be vague, each is evaluated on its own merit.
* Kodi code improvements
* Reduce support load for add-on developers
* Reduce workload for repository maintainers


* All skins must be 100% valid XML. You should validate your code before submitting. Windows users can use the Notepad++ plugin for this.
Below is a table of on which submissions are allowed to official Kodi repository.
* Skins must not include any scripts or plugins. If you need a script, submit it separately and depend on it.
* Any themes must be in a subfolder of the themes/ in the skin root. This is to ensure that TexturePacker picks them up correctly.
* Due to a bug in TexturePacker, all graphics files should have a resolution of at least 4x4.
* All paths should be treated as case-sensitive, so that they work on all OSs and filesystems.
* If you want to have some images outside of Textures.xbt, then make sure you place those images outside of the media/ folder and reference them using special://skin/backdrops/* or similar.  This is most useful for backgrounds - it keeps the size of the packed textures down.  Any images you have in the media/ folder will be placed in Textures.xbt in the official repository.
* All skins starting with Frodo must have a fanart.jpg included in the root dir. This must be a 1280x720 or 1920x1080 sized jpeg image.
* All skins starting with Eden must have a _screenshots folder included in the root dir and filled with 5-10 reasonably sized 1280x720 jpeg screenshots. For ex: skin.sample/_screenshots/screenshot01.jpg
* Note that .xbt files will be generated automatically for skins so you do not include this in your request.


==== Optional support ====
{| class="prettytable" border="1"
|+ Allowed add-on submissions
! codename !! version !! update !! new
|-
| Dharma || 10.x || no || no
|-
| Eden || 11.x || no || no
|-
| Frodo || 12.x || no || no
|-
| Gotham || 13.x || yes || no
|-
| Helix || 14.x || yes || no
|-
| Isengard || 15.x || yes || no
|-
| Jarvis || 16.x || yes || no
|-
| Krypton || 17.x || yes || no
|-
| Leia || 18.x || yes || no
|-
| Matrix || 19.x || yes || yes
|-
| Nexus || 20.x || yes || yes
|}


This is optional and should not block inclusion in official repo.


* mouse support
Additional feature is that we now use combined repositories. So if your add-on is Gotham/Helix compatible, you only need to send it to Gotham repository.
* touchscreen support
If it's only Helix compatible you need to send it to Helix repository.
* karaoke dialogs
This of course requires that the minimal Kodi dependencies are set accordingly.
* peripheral dialogs
* pvr support


{| class="prettytable" border="1"
|+ Which repos are used for Python add-ons (scripts, scrapers and plugins)
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || Gotham || Helix || Isengard
|-
| Jarvis || 16.x || Gotham || Helix || Isengard  || Jarvis
|-
| Krypton || 17.x || Gotham || Helix || Isengard  || Jarvis  || Krypton
|-
| Leia || 18.x || Gotham || Helix || Isengard  || Jarvis  || Krypton || Leia
|-
| Matrix|| 19.x || - || - || - || - || - || - || Matrix
|-
| Nexus|| 20.x || - || - || - || - || - || - || Matrix || Nexus
|}


==== Basic sanity checks ====
{| class="prettytable" border="1"
Here's a list of what basic sanity checks are done by repo maintainer on each submission.
|+ Which repos are used for skins
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || || || Isengard
|-
| Jarvis || 16.x || || || || Jarvis
|-
| Krypton || 17.x || || || || || Krypton
|-
| Leia || 18.x || ||  || || || || Leia
|-
| Matrix|| 19.x || || || || || || || Matrix
|-
| Nexus|| 20.x || || || || || || || Matrix || Nexus
|}


'''Basic file checks:'''
{| class="prettytable" border="1"
|+ Which repos are used for other add-ons
! codename !! version !! repos !!colspan="8"| repo
|-
| Dharma || 10.x || Dharma
|-
| Eden || 11.x || Eden
|-
| Frodo || 12.x || Frodo
|-
| Gotham || 13.x || Gotham
|-
| Helix || 14.x || Gotham || Helix
|-
| Isengard || 15.x || Gotham || Helix || Isengard
|-
| Jarvis || 16.x || Gotham || Helix || Isengard  || Jarvis
|-
| Krypton || 17.x || Gotham || Helix || Isengard  || Jarvis  || Krypton
|-
| Leia || 18.x || Gotham || Helix || Isengard  || Jarvis  || Krypton || Leia
|-
| Matrix || 19.x || Gotham || Helix || Isengard  || Jarvis  || Krypton || Leia || Matrix
|-
| Nexus || 20.x || Gotham || Helix || Isengard  || Jarvis  || Krypton || Leia || Matrix || Nexus
|}


* all .xml files must pass xml validation
{{see also|Addon.xml#Dependency_versions}}
* all .xml files must have xml declaration as header
* all .xml/.txt must have unix style EOL's
* don't use a BOM at the start of your files
* file permissions: files should not be marked as executable
* filenames must have correct encoding (check your studio logos for corrupt filenames)


=== Github ===


'''Things that must be included:'''
==== Pull requests ====
New add-ons or updates may be submitted directly to the [[Official add-on repository]] on Github as pull requests. We are aware that this requires some initial git knowledge and we strongly suggest to read up on this subject before submitting a pull request.


* addon.xml must contain correct and valid info / versioning
To reduce size we have split up the git repositories in several locations. Please visit [[Official add-on repository]] to see where they are. Each contains a small readme with a short description of it's contents as well as a link to a short explanation on how to submit using git command line. There are also git tools available that have a graphic interface and the steps above should be done in a similar way. Please consult the manual of those programs.
* LICENCE.txt must be present
* icon.png must be present (256x256)
* fanart.jpg must be present (1280x720 or 1920x1080)
* _screenshots folder must be present, containing max. 10 .jpg screenshots (1280x720)


In addition to the [[Add-on rules|repository guidelines]] the following rules apply when submitting PRs on Github:


'''Things that can't be included:'''
* PR should contain one commit only.
* Commit message should have the format "[addonid] version". Example: "[my.cool.addon] 1.0.1"


* no .xbt files
If Team Kodi reviewers asked you to make some changes in your PR, follow this procedure: [[HOW-TO: Update a pull request to an official addon repository on GitHub]].
* no scripts included
* don't include unneeded files (.pdf, .doc, thumbs.db, etc...)
* no licensed fonts / background images / anything


Only PRs from the add-on author or his successor will be accepted. Patches should be submitted upstream to the original author first. For an easy way to create PR from your own git repository, see [[HOW-TO: create add-on PRs using Git Subtree Merging]].


'''Code checks:'''
==== Issue ticket ====


* all labels must be localized
'''This route is only available for skins in https://github.com/xbmc/repo-skins.
* code should be case-sensitive
'''
* skins should not create warning/errors in the logfile, this can be a lot of things:
:* invalid includes
:* undefined actions
:* unable to evaluate condition
:* undefined vars
:* can't focus 'id'


=== Requirements for scripts and plugins ===
For skins submissions you may also use the "issue" option where you submit a request to get you add-on added. In this ticket you need to provide the basic information needed so our repo maintainers know where to get the correct version.  
* all .xml files must have xml declaration as header
This consists of
* os.getcwd() is deprecated, please use getAddonInfo('path') instead
  - Add-on name:
* all special:// paths should be translated using xbmc.translatePath("special://foo/bar")
  - Add-on ID:
* All scripts starting with Eden must have a fanart.jpg included in the root dir with a 1280x720 / 1920x1080 sized jpeg screenshot.
  - Version number:
* Direct access to the XBMC database is '''not''' allowed. You must use [[JSON RPC]] for this.
  - Kodi/repository version:
* Directly using analytics (Google Analytics for example) from within addons is not allowed. This should be handled server side by using user-agent.
  - Code location URL:
* Add-ons should store all their data in their own subfolder inside the addon_data directory. Access (read/write/delete) to any other files in settings folders is not allowed. Access (read/write/delete) to other all other files/directories must be opt-in by the user, and be clear for the user to understand what is being accessed. ''Exceptions to this rule may be granted in specific cases only. Please contact Team XBMC's add-on repository maintainers via the add-on mailing list if your add-on needs access to such files.''
  - Revision/tag:
  - Branch:


=== Requirements for scrapers ===
Further information is provide when you initially create the issue on github as comments in the ticket.
* scraper must return the following minimum information: movie title, year, plot, cast, poster, fanart
Same [[Add-on rules|repository guidelines]] apply here as well.
* use 'chain function' for calling functions in common scrapers
* remove the deprecated XML tags from the scraper header in case you use a scraper editor made for pre-Dharma versions of XBMC
* all .xml files must have xml declaration as header


== Submitting a Compliant Add-on to the XBMC.org Repo ==
==== How to submit your add-on and subsequent updates ====
Submitting updates is done the same way as with pull requests or issue ticket.


After you have read the above repository guidelines and made sure your addon is compliant with them, you may begin the submission process using the following steps.
==== Repository lists ====
You can create pull requests or tickets on the following individual repositories.


=== The mailing list ===
  https://github.com/xbmc/repo-plugins
We ask that all Add-on authors subscribe to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List].
  https://github.com/xbmc/repo-resources
This is done for several reasons.
  https://github.com/xbmc/repo-scrapers
:* This is where all updates and important information will be announced.
  https://github.com/xbmc/repo-scripts
:* This way we can contact you regarding your add-ons if necessary.
  https://github.com/xbmc/repo-skins
:* You can see what other devs are requesting to be added so you know if possibly you need to check compatibility of the add-on you depend on.
  https://github.com/xbmc/repo-webinterfaces
:* You may find new and interesting add-ons this way on which you can get inspiration from or may depend on.


All pull requests should be sent to this list so that repo maintainers will be notified that you want to add of update your add-on. They will do a sanity check if all seems ok and you are following the XBMC guidelines for add-ons. If any issues or questions arise they will contact you through the e-mail you registered with.
=== Additional information ===
Once all checks out fine your add-on is added to repo and you will receive a confirmation e-mail that it is added.
Note that skin .xbt files will be generated automatically for skins so you do not include this in your pull request or created tickets.  
After the add-on has been added or updated it will be available from the Kodi repository in Kodi itself, on http://addons.kodi.tv/ and on the wiki page http://kodi.wiki/index.php?title=Category:All_add-ons.


{{Note|Please locate you add-on in the root of the git repository. This to make sure we can easily pull the add-on into our repository.
Example: https://github.com/XBMC-Addons/service.xbmc.versioncheck}}


{{tip|To un-subscribe from the mailinglist follow the same link as [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] and there's the option to unsubscribe at the bottom}}


=== How to submit your add-on and subsequent updates ===
{{tip|We automatically combine all repos into one single repo list on our server and provide that list to Kodi. You only need to do a request for the minimum repo your add-on supports.}}


In order to submit your addon, you must send a request that we add or update your add-on to the [https://lists.sourceforge.net/lists/listinfo/xbmc-addons Add-ons Mailing List] (We call this a "pull request."). Each request will require a version bump in the [[addon.xml]]. We ask that you also keep a [[Add-on development#changelog.txt|changelog.txt]] up to date so that users may easily see what has changed.
=== The mailing list ===
 
Note that .xbt files will be generated automatically for skins so you do not include this in your pull request.
 
There are several ways to request that we add or update your add-on. Please preface threads using the following conventions:
 
{| class="wikitable" border="1"
! Type !! Description
|-
| [Git Pull]|| Submit a request that we pull from your repo. This should include a url, branch/tag/revision, and the addon to pull. HEAD is NOT a revision.
|-
| [SVN Pull]|| Same as [Git Pull]
|-
| [Zip Pull]|| By far the least used but still a valid way. Submit a link where the add-on zip can be downloaded from.
For example you can just give us the link to .zip in your dropbox account. We do not want to download it from a public download site that holds questionable content or is filled with ads.
|-
| [Patch]|| Sometimes you may wish to submit a patch to the author for review.
Under most circumstances we will not merge this directly, it should go to the upstream maintainer first.
|}
 
=== Example e-mail ===
 
Subject:
  [Git Pull] my cool plugin
Body:
  *addon -  my.cool.plugin
  *version - 1.1.0
  *url - git://some.where.git
  *revision - a241345a
  *branch - master
  *xbmc version - frodo
 
 
{{Note|If you want to request multiple add-ons to be added you can just do this in one e-mail as long as you provide the "Body" part each time for every add-on and every XBMC version you want it to be included to. In this case the subject field doesn't need to contain the add-on name. Do provide the "[Git Pull]" part at least.}}
 
 
{{tip|You have to do separate pull requests for each repository (Eden, Frodo/Gotham).}}


{{tip|At this moment Frodo and Gotham share the same repo so doing one request for Frodo/Gotham is enough.}}
''' MAILINGLIST IS NOT USED ANYMORE. ALL REQUESTS SHOULD GO THROUGH GITHUB '''


[[Category:Addon Development]]
[[Category:Add-on development]]

Latest revision as of 23:06, 29 December 2021

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Submitting Add-ons


Submitting a Compliant Add-on to the Kodi.tv Repo

After you have read the repository guidelines and made sure your addon is compliant with them, you may begin the submission process using the following steps.

Allowed submissions

We have restricted the allowed submissions of add-ons to past Kodi versions. Several reasons:

  • Kodi code improvements
  • Reduce support load for add-on developers
  • Reduce workload for repository maintainers

Below is a table of on which submissions are allowed to official Kodi repository.

Allowed add-on submissions
codename version update new
Dharma 10.x no no
Eden 11.x no no
Frodo 12.x no no
Gotham 13.x yes no
Helix 14.x yes no
Isengard 15.x yes no
Jarvis 16.x yes no
Krypton 17.x yes no
Leia 18.x yes no
Matrix 19.x yes yes
Nexus 20.x yes yes


Additional feature is that we now use combined repositories. So if your add-on is Gotham/Helix compatible, you only need to send it to Gotham repository. If it's only Helix compatible you need to send it to Helix repository. This of course requires that the minimal Kodi dependencies are set accordingly.

Which repos are used for Python add-ons (scripts, scrapers and plugins)
codename version repos repo
Dharma 10.x Dharma
Eden 11.x Eden
Frodo 12.x Frodo
Gotham 13.x Gotham
Helix 14.x Gotham Helix
Isengard 15.x Gotham Helix Isengard
Jarvis 16.x Gotham Helix Isengard Jarvis
Krypton 17.x Gotham Helix Isengard Jarvis Krypton
Leia 18.x Gotham Helix Isengard Jarvis Krypton Leia
Matrix 19.x - - - - - - Matrix
Nexus 20.x - - - - - - Matrix Nexus
Which repos are used for skins
codename version repos repo
Dharma 10.x Dharma
Eden 11.x Eden
Frodo 12.x Frodo
Gotham 13.x Gotham
Helix 14.x Gotham Helix
Isengard 15.x Isengard
Jarvis 16.x Jarvis
Krypton 17.x Krypton
Leia 18.x Leia
Matrix 19.x Matrix
Nexus 20.x Matrix Nexus
Which repos are used for other add-ons
codename version repos repo
Dharma 10.x Dharma
Eden 11.x Eden
Frodo 12.x Frodo
Gotham 13.x Gotham
Helix 14.x Gotham Helix
Isengard 15.x Gotham Helix Isengard
Jarvis 16.x Gotham Helix Isengard Jarvis
Krypton 17.x Gotham Helix Isengard Jarvis Krypton
Leia 18.x Gotham Helix Isengard Jarvis Krypton Leia
Matrix 19.x Gotham Helix Isengard Jarvis Krypton Leia Matrix
Nexus 20.x Gotham Helix Isengard Jarvis Krypton Leia Matrix Nexus

Github

Pull requests

New add-ons or updates may be submitted directly to the Official add-on repository on Github as pull requests. We are aware that this requires some initial git knowledge and we strongly suggest to read up on this subject before submitting a pull request.

To reduce size we have split up the git repositories in several locations. Please visit Official add-on repository to see where they are. Each contains a small readme with a short description of it's contents as well as a link to a short explanation on how to submit using git command line. There are also git tools available that have a graphic interface and the steps above should be done in a similar way. Please consult the manual of those programs.

In addition to the repository guidelines the following rules apply when submitting PRs on Github:

  • PR should contain one commit only.
  • Commit message should have the format "[addonid] version". Example: "[my.cool.addon] 1.0.1"

If Team Kodi reviewers asked you to make some changes in your PR, follow this procedure: HOW-TO: Update a pull request to an official addon repository on GitHub.

Only PRs from the add-on author or his successor will be accepted. Patches should be submitted upstream to the original author first. For an easy way to create PR from your own git repository, see HOW-TO: create add-on PRs using Git Subtree Merging.

Issue ticket

This route is only available for skins in https://github.com/xbmc/repo-skins.

For skins submissions you may also use the "issue" option where you submit a request to get you add-on added. In this ticket you need to provide the basic information needed so our repo maintainers know where to get the correct version. This consists of

 - Add-on name: 
 - Add-on ID:
 - Version number:
 - Kodi/repository version:
 - Code location URL:
 - Revision/tag: 
 - Branch:

Further information is provide when you initially create the issue on github as comments in the ticket. Same repository guidelines apply here as well.

How to submit your add-on and subsequent updates

Submitting updates is done the same way as with pull requests or issue ticket.

Repository lists

You can create pull requests or tickets on the following individual repositories.

 https://github.com/xbmc/repo-plugins
 https://github.com/xbmc/repo-resources
 https://github.com/xbmc/repo-scrapers
 https://github.com/xbmc/repo-scripts
 https://github.com/xbmc/repo-skins
 https://github.com/xbmc/repo-webinterfaces

Additional information

Note that skin .xbt files will be generated automatically for skins so you do not include this in your pull request or created tickets. After the add-on has been added or updated it will be available from the Kodi repository in Kodi itself, on http://addons.kodi.tv/ and on the wiki page http://kodi.wiki/index.php?title=Category:All_add-ons.

Note: Please locate you add-on in the root of the git repository. This to make sure we can easily pull the add-on into our repository. Example: https://github.com/XBMC-Addons/service.xbmc.versioncheck


Tip Tip: We automatically combine all repos into one single repo list on our server and provide that list to Kodi. You only need to do a request for the minimum repo your add-on supports.

The mailing list

MAILINGLIST IS NOT USED ANYMORE. ALL REQUESTS SHOULD GO THROUGH GITHUB