Official add-on repository

Beginning with Dharma, XBMC includes an interface to browse remote repositories where add-ons can be retrieved. The model is similar to the way many current Linux distributions work, whereby there is a "main" repository that is the default, and additional ones may be added by the user. The Official xbmc.org Repository is included with XBMC by default and is maintained by the XBMC team. This page outlines how to submit your addon to the official repository and keep it up to date.

Contents 1 Add-on requirements 2 The repositories 3 Branches 4 The mailing list 5 How to submit your add-on and subsequent updates 5.1 Example e-mail 6 Repository guidelines 6.1 Updates 6.2 Requirements for skins 6.3 Requirements for scripts 6.4 Requirements for scrapers 7 See also

1 Add-on requirements

In order to be considered for the official repository, the following guidelines must be met:

• All addons must be developed as described on the Add-on development page and in the Addon Developers Guide.
• You MUST include a license file. We recommend the CC-BY-SA 3.0 for skins and the GPL v2+ for others, but most copyleft licenses will suffice.
• All files must be free and legal to distribute.
• The addon 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.
• Please follow the Guidelines for images
• Please follow the Technical Guidelines

2 The repositories

XBMC uses git to manage the official repository. See below for the list of git repositories that comprise it.

 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/plugins
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/scrapers
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/screensavers
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/scripts
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/skins
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/visualizations
 git clone git://xbmc.git.sourceforge.net/gitroot/xbmc/webinterfaces

3 Branches

At any given time, there will be two active branches for each repository: stable, and stable-pre. At the time of this writing, Eden-pre is the main branch for development. When Eden final is released, all add-ons that are compatible will be moved to Eden branch. Developers are asked to maintain compatibility with stable branches first, and bleeding-edge (-pre) as their time and effort allows.

4 The mailing list

We ask that all Add-on authors subscribe to the Add-ons Mailing List. This is where all updates and important information will be announced. In addition, all pull requests should be sent to this list.

5 How to submit your add-on and subsequent updates

As mentioned above, in order to submit your addon, you must send a pull request to the mailing list address found in the link above. Each pull will require a version bump in the addon.xml. We ask that you also keep a changelog.txt up to date so that users may easily see what has changed. To be sure that all addons are maintainable in the future, the following filetypes are banned from the official repository: .pyo, .pyd, .xbt, .xpr, .so, .dll. Note that .xbt files will be generated automatically for skins.

There are several ways to request that we add or update your addon. Please preface threads using the following conventions:

 *[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] - See above.
 *[Zip Pull] - By far the least useful. Submit a link to the addon or update.
 *[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.

5.1 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 - dharma

6 Repository guidelines

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 a pull request.

• You MUST include a license file. We recommend the CC-BY-SA 3.0 for skins and the GPL v2+ for others, but most copyleft licenses will suffice.
• All files must be free and legal to distribute.
• The addon 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.
• Please follow the Guidelines for images

Please note that you have to do seperate pull requests for each repository (dharma, eden).

6.1 Updates

Keep in mind that addons 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 addon 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 pull 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).

6.2 Requirements for skins

• The filesize 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 they are only confusing to non-forum-goers. This can be vague, each is evaluated on its own merit.
• The following fileypes are not allowed: .so .dll .pyo .exe .xbt .xpr Thumbs.db
• All skins must be 100% valid XML. You should validate your code before submitting. Windows users can use the Notepad++ plugin for this.
• 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 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

6.3 Requirements for scripts

• os.getcwd() is depreciated, please use getAddonInfo('path') instead
• all special:// paths should be translated using xbmc.translatePath("special://foo/bar")
• all scripts must be localized, no hardcoded language strings should ever be used

6.4 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 depreciated XML tags from the scraper header in case you use a scraper editor made for pre-Dharma versions of XBMC

7 See also

• Add-ons
• Category:All add-ons
• 3rd party add-on repositories

Development:

• Add-on development
• Python development
• Skinning
• Add-on repositories