Difference between revisions of "Add-on rules"

From Official Kodi Wiki
Jump to: navigation, search
(Requirements for skins)
(Optional support)
Line 86: Line 86:
This is optional and should not block inclusion in official repo.
This is optional and should not block inclusion in official repo.
* mouse support
* Mouse support
* touchscreen support
* Touchscreen support
* peripheral dialogs
* Peripheral dialogs
* PVR support
* PVR support
* ADSP support
* ADSP support
* RDS support
* RDS support
* Game support
=== Requirements for scripts and plugins ===
=== Requirements for scripts and plugins ===

Revision as of 02:32, 1 February 2019

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Add-on rules

1 Repository Submission Guidelines - Please Read Before Submitting Your Addon

Inclusion in the Kodi.org repository is at the sole discretion of Team Kodi. 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 CC-BY-SA 3.0 for skins and the GPL v2+ for others, but most copy left licenses will suffice. Please investigate which license suits your needs and you fully understand the contents.
  • 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 will be allowed.
  • You acknowledge that you are the maintainer of your add-on.
  • Team-Kodi reserves the right to update or remove it at any time as we deem necessary.
  • If a new stable Kodi is going to be released no new submissions are accepted to the repository for the previous version. This will start from when the first 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 13.x, no updates are allowed for 11.x any more). See: Allowed submissions
  • Monetization of add-ons (for instance advertising or paid subscriptions) will not be allowed. We can make an exception in case you own the copyright for the content the add-on provides. Please contact us on the forum (or add-on mailing list) if you believe such an exception may apply to your add-on.
  • All xbmc.python.module addons must be used by at least one other add-on in official repository.

2 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. Too often is of course subjective. 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 or twice per month is probably a better goal, barring unforeseen conditions (like a content source changing its paths). With good reasons provided we will of course make exceptions as we strive to prove the best user experience.

3 General requirements

Here's a list of what basic sanity checks are done by repository maintainer on each submission.

Basic file checks:

  • all strings used by add-ons must be localized, no hard-coded language strings should ever be used
  • all paths should be treated as case-sensitive, so that they work on all OSs and file systems.
  • all paths and files should be lower-case due to the previous point
    • exceptions are README, COPYING, LICENSE.txt that should be upper-case and the "Default" directory in resources/skins, for add-ons that need it.
  • exception are the translation language folders which should be first letter capitalized.
  • the following file-types are not allowed: .so .dll .pyo .exe .xbt .xpr Thumbs.db and so on<any binary files>
  • all text files should use UNIX end-of-line
  • all .xml files must pass xml validation
  • 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 (for skins: check your studio logos for corrupt filenames)

Things that must be included:

  • addon.xml must contain correct and valid info / version
  • icon.png must be present (256x256) or (512x512)
  • fanart.jpg must be present (1280x720 or 1920x1080 or 3840x2160)
  • LICENSE.txt must be present

Things that can't be included:

  • no .xbt files (these will be generated by our repository)
  • no other add-ons included (skinners: if you need a script, submit it separately and depend on it)
  • don't include unneeded files (.pdf, .doc, thumbs.db, etc...)
  • no licensed fonts / background images / anything

4 Requirements for skins

Basic checks:

  • The file size must be sane. There is no hard limit, but a 100mb skin is pushing it.
  • No mods. Mods are great, and pop up frequently in the forums. But we would rather not have several versions of the same skin in our repo. But if your mod is substantial different enough from the original (and by giving it a different name), we will of course take it in consideration. Also if the original skin is no longer available through our repo, we would have no problem replacing it with a mod.
  • Due to a bug in TexturePacker, all graphics files should have a resolution of at least 4x4.
  • themes must be in a subfolder of the themes/ folder in the skin root (eg. skin.foo/themes/blue/<files>). The .xbt file will be created by our repo backend.
  • 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.
  • Please be careful with addon dependencies. Only add dependencies that are needed for the skin to function properly.

Code checks:

  • all labels must be localized
  • 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'

Note: This of course also applies to script add-ons that use skin files

4.1 Optional support

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

  • Mouse support
  • Touchscreen support
  • Peripheral dialogs
  • PVR support
  • ADSP support
  • RDS support
  • Game support

5 Requirements for scripts and plugins

  • all special:// paths should be translated using xbmc.translatePath("special://foo/bar")
  • xbmc.translatePath(xbmcaddon.Addon().getAddonInfo('path')).decode('utf-8') should be used for files included with the add-on
  • xbmc.translatePath(xbmcaddon.Addon().getAddonInfo('profile')).decode('utf-8') should be used for storing add-on related files
  • direct access to the Kodi database is not allowed. You must use JSON RPC for this.
  • directly using analytics (Google Analytics for example) from within add-ons is not allowed. This should be handled server side by using user-agent.
  • addons should use the xbmc.log() method to write to the logfile and use the debug logging level only. print statements should not be used.
  • Plugins should not force certain skin viewtypes on their own. They should set the correct media content from which the correct skin view type is automatically provided.
  • add-ons should store all their data in their own subfolder inside the addon_data directory. Access (read/write/delete) to any other files / folders is not allowed by default.

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. In case we grant such an exception for your addon, access (read/write/delete) to other files/directories must be opt-in by the user, and be clear for the user to understand what is being accessed.

6 Requirements for scrapers

  • scraper must return the following minimum information: movie title, year, plot, cast, poster, fanart
  • 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