Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
plugin_store_guidelines [2017/11/27 17:00] – [Release Requirements] jayplugin_store_guidelines [2026/04/07 18:27] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +===== Plugin Store Submission Guidelines =====
 +This document outlines the rules for submitting a plugin to the [[http://www.indigodomo.com/pluginstore/|Indigo Plugin Store]]. While it may seem like a lot, it's mostly common sense. You can start the process from the [[https://www.indigodomo.com/account/plugins|Plugin Contributions section of your Indigo Account]].
 +
 +**<color #ed1c24>NOTE</color>**: due to a configuration option on our backend system database, plugins with releases or README.md <color #ed1c24>files that contain emoji's will fail</color>. We intend to correct this at some point this year (2026), but for the time being please remove emojis from those files or they will fail to add to the store.
 +==== Creating Your Developer Account ====
 +If you haven't already, you'll need to go to the [[https://www.indigodomo.com/account/plugins|Plugin Contributions]] page in your Indigo Account and add your developer information:
 +
 +{{:plugin_contributions.png?nolink|Plugin Contributions Image}}
 +
 +Please read through the entire top section of that page as it contains important information.
 +
 +**Warning**: please **do not use** ''com.indigodomo'' or ''com.perceptiveautomation'' as your developer ID (or embed those in your developer id). Those are our internal IDs and should not be used.
 +
 +==== Adding A Plugin ====
 +First and foremost: please //do not// attempt to add a plugin that you don't "own." If a developer of a plugin has abandoned it and you would like to take it over, please let us know and we'll take it from there (we've done this in the past and it's usually not a problem). Once we get permission we'll let you know and we can coordinate from there. If the developer is still active, let them know that you'd like to see it in the Plugin Store.
 +
 +There are two ways to add a plugin:
 +
 +{{ :add_plugin_1.png?nolink&400 |Add Plugin Image}}
 +
 +The first and recommended option is via a GitHub Repository. You'll manage your plugin almost completely through GitHub. You'll create releases there, manage the various descriptions, etc. You will have the option to override some of that information in the plugin administration UI that we provide, but you'll likely find that managing everything through GitHub will be a better and more consistent experience.
 +
 +The other option is to directly manage everything through our UI. With this approach you'll create your own plugin releases and upload each new release via our plugin administration UI. You'll need to manage all descriptions through our UI. If you don't want to learn how to use GitHub then this is the option for you.
 +
 +==== General Rules ====
 +First, some general rules that you need to follow regardless of which approach you take:
 +
 +  * Version numbers in the ''Info.plist'' file must be of the form X.Y.Z (except the ServerApiVersion, which is X.Y). There are no beta/pre-release signifiers allowed.
 +  * No two releases can have the same version number (X.Y.Z).
 +  * The Plugin ID (CFBundleIdentifier) can't change once a plugin has been added.
 +  * The Plugin ID **must begin with your developer ID** specified above. This **should not** begin with ''com.indigodomo'' or ''com.perceptiveautomation''. So, if you specified ''com.johnsmith'' as your developer id, your plugin IDs would look like ''com.johnsmith.myfirstplugin''.
 +  * If the ''Contents/Resources/icon.png'' file exists in your Plugin bundle it will be used as the icon in the store (the {{:plugin_128x128.png?nolink&24|Plugin Image}} icon will be used if the file doesn't exist). See [[#Icons and Branding]] below for more details.
 +  * Plugins and releases can only be deleted by Indigo Domotics staff. Email us with details if you need a release removed.
 +
 +==== GitHub Specifics ====
 +If you want to use GitHub (and there are many advantages to doing so), there are a few things to consider. We have a few (but not many) requirements in how your repo is constructed and how you do releases. There are also some optional things that you'll want to consider to make the experience for users even better.
 +
 +If you're new to GitHub but want to try it out, we've written [[https://wiki.indigodomo.com/doku.php?id=developer:github_setup_for_plugins|a simple How-To]] with lots of screen captures describing one way to set up your repository.
 +
 +=== GitHub Repo Layout ===
 +This is the required GitHub Repo layout:
 +
 +{{ :github_repo_layout.png?nolink&600 |GitHub Repo Layout Image}}
 +
 +At the top level of the repo should be your plugin folder and an optional ''README'' file. You may have other files in there as well, like the ''LICENSE'' file in the rachio-indigo repo above. The plugin is there for obvious reasons – it's the path into the source for your plugin. The ''README'' file's contents will automatically be used as plugin's description and shown on the About tab on your Plugin's detail page:
 +
 +{{ :rachio-pluginstore-detail.png?nolink&600 |Rachio Plugin Store Detail Image}}
 +
 +Markdown in the ''README.md'' file will be rendered correctly in the Plugin Store though you can also use a plain text file (''README.txt'').
 +
 +=== GitHub Releases ===
 +When you are ready to publicly release a version of the plugin (either initially or a follow-up release), you should add a release in GitHub:
 +
 +{{ :github-releases.png?nolink&600 |GitHub Releases Image}}
 +
 +We **do not** look at the "master branch" (or "tips") of the repo. Only published releases (not pre-releases) will be added to the Plugin Store's release list (see [[#Adding a GitHub Release]] below for details). The Plugin Store currently doesn't support listing betas (pre-releases) but you can still create them and point your beta testers to them on GitHub (one of the advantages to using GitHub).
 +
 +== Release Requirements ==
 +There are a few requirements for GitHub releases:
 +
 +  * The GitHub release tag # must match PluginVersion in ''Info.plist'' file, otherwise the release will be rejected when added to the Plugin Store. <color red>Note</color>: we will be looking in the source code zipball from the release for the Info.plist, __not__ the attached plugin. If you're getting the mismatch error, that's where you'll need to look to fix any mismatching version numbers.
 +  * The ''README.md'' or ''README.txt'' file must be at the top level of the archive for it to automatically be used. This is to avoid issues if your plugin includes other source projects that may also have their own README files.
 +  * Although optional, we strongly encourage you to add a zipped version of just the plugin folder (not the entire repo) to each release. Make sure that 'indigoPlugin' is in the name and that it's a zip file (i.e. ''MyPlugin.indigoPlugin.zip'') and make sure that there aren't any other zip files attached to the release. If you don't include an attached zipped plugin, the user will download a zipped copy of the repo itself, including the plugin, the README, etc. (basically everything in the repo). This may make it confusing for users to find and install the plugin.
 +
 +==== Adding a Plugin ====
 +As we mentioned at the top, there are two ways to add a new plugin to the Plugin Store: by specifying a GitHub repo or by uploading an existing plugin:
 +
 +{{ :add_plugin_1.png?nolink&400 |Add Plugin Image}}
 +
 +<color red>**Note:**</color> There is no automated way to convert between a github-based plugin and a directly managed plugin, so please carefully consider which approach you want to use before initially adding the plugin (we recommend GitHub!). We can manually convert between the two, but it takes some time and effort.
 +
 +=== Adding a Plugin from GitHub ===
 +To add a new plugin from a GitHub repo, just enter the GitHub user and repo names. As an example, for our Rachio Sprinkler repo, which is located here:
 +
 +''https://github.com/IndigoDomotics/rachio-indigo''
 +
 +We entered **IndigoDomotics** for the user and **rachio-indigo** as the repo. Note your repo must have at least one published release to be added to the Plugin Store.
 +
 +Click the **''Next''** button and you'll see the following page with the appropriate data pre-populated:
 +
 +{{ :add_plugin_from_github.png?nolink&600 |Add Plugin From GitHub Image}}
 +
 +This form has a variety of fields (some read-only) that fall into two groups. The first group are fields about the plugin itself (not any specific release of the plugin):
 +
 +  - **Plugin ID** - the ID from the ''Info.plist'' file (read-only).
 +  - **Name** - the name from the ''Info.plist'' file (read-only).
 +  - **Summary*** - a very brief (200 character) summary of your plugin. It is pre-populated with the description for your GitHub repo but you may edit it as you want. It will never be overwritten from GitHub.
 +  - **Description*** - the ''README'' file's contents from the repo will be inserted here. It may contain Markdown and you can edit it to make any changes you like. You will have the option of updating it from GitHub when you add new releases.
 +  - **Category** - the major category of your plugin. If you can't find one that seems suitable, then select **Miscellaneous**. This can be changed later.
 +  - **Help URL*** - the help URL pre-populated from the ''Info.plist''. You may override it and it will never be overwritten automatically.
 +  - **Documentation URL** - a separate and optional URL that can point to more comprehensive documentation. This is a good place to put the URL to the GitHub wiki for this repo (see the [[https://github.com/IndigoDomotics/rachio-indigo/wiki|Rachio Plugin's wiki page]] for an example).
 +  - **Plugin Icon** - if your plugin's bundle has an icon (''Contents/Resources/icon.png'' file) then it will automatically be used if you leave this field blank. Alternately, you can add a PNG file here.
 +  - **GitHub User and Repo** - a read-only copy of what you entered on the first screen.
 +
 +And the next section is specific information about the release that you're adding:
 +
 +  - **Release Version** - automatically retrieved from the releases section of GitHub. If you have more than one release in the repo, this will be the most recent (only repos that are not pre-release or draft are used). **Note**: the release version number in the GitHub release source zip's Info.plist **must match** the tag for the GitHub release. Otherwise, the release will not be added. This sanity check will help ensure that you don't end up with version mismatches and the associated problems that will result (failed update checking, failed upgrades, etc).
 +  - **Release Title** - also retrieved from GitHub, it's the short release title.
 +  - **What's New** - again, retrieved from GitHub, this is the full description of the release.
 +  - **Requirements** - an optional separate field that may contain Markdown. The intention of this field is to outline any specific requirements or steps needed to perform for this release. GitHub doesn't have anywhere (other than the release description) to put this kind of information. You may, of course, just add it to the description (and therefore the What's New section) and leave this field blank. We won't show it if it's blank.
 +  - **Date Released** - the release date as specified in the GitHub release info. You can change it here if you like, using the YYYY-MM-DD format. Note if you change it to some date in the future it won't show up in the Plugin Store until that date.
 +  - **Server API** and **Bundle Versions** - retrieved from the ''Info.plist'' and just shown here for completeness. The Server API version is particularly important in that it determines what's shown as the minimum Indigo version required to use the plugin.
 +
 +Required fields are marked with an asterisk (*). The majority of GitHub repos will have all the information needed for the required fields so it's only likely that you'll have to edit the Category field as a minimum (and if your plugin is an A/V or IR plugin you won't even have to do that!). Once you have reviewed all the form fields hit ''**Add Plugin**''.
 +
 +You'll notice that on the right side of the screen we've provided a quick cheatsheet for Markdown syntax. This will be helpful when editing any fields that allow Markdown.
 +
 +=== Adding a Directly Managed Plugin ===
 +To add a new plugin from an existing zipped plugin, just click the Choose File button and select the file. Note that Safari will automatically zip plugin folders before uploading (but your browser of choice may not).
 +
 +Click the **''Next''** button and you'll see the following page (with the appropriate data pre-populated):
 +
 +{{ :add_plugin_from_file.png?nolink&600 |Add Plugin From File Image}}
 +
 +This form has a variety of fields (some read-only) that fall into two groups. The first group are fields about the plugin itself (not any specific release of the plugin):
 +
 +  - **Plugin ID** - the ID from the ''Info.plist'' file (read-only).
 +  - **Name** - the name from the ''Info.plist'' file (read-only).
 +  - **Summary*** - a very brief (200 character) summary of your plugin.
 +  - **Description*** - a full description of what your plugin does. The field may contain Markdown.
 +  - **Category** - the major category of your plugin. If you can't find one that seems suitable, then select **Miscellaneous**.
 +  - **Help URL*** - the help URL pre-populated from the ''Info.plist''. You may override it and it will never be overwritten automatically. Commonly developers use this URL to point to a specific post on [[https://forums.indigodomo.com/viewtopic.php?f=121&t=7526 | their own sub-forum]].
 +  - **Documentation URL** - a separate and optional URL that can point to more comprehensive documentation. So if you have a forum post that contains the documentation for the plugin for instance (and if it's different than the Help URL) then this is the place to put it.
 +  - **Plugin Icon** - if your plugin's bundle has an icon (at ''Contents/Resources/icon.png'') then it will automatically be used if you leave this field blank. Alternately, you can add a PNG file here that will be used in the plugin's display in the Plugin Store.
 +  - **GitHub User and Repo** - disabled since this plugin will be managed directly through our pages.
 +
 +And the next section is specific information about the release that you're adding:
 +
 +  - **Release Version** - automatically retrieved from the ''Info.plist'' file.
 +  - **Release Title*** - a short summary (100 characters max) of this release of the plugin.
 +  - **What's New*** - a full description of the release. This field may contain Markdown.
 +  - **Requirements** - an optional separate field that may contain Markdown. The intention of this field is to outline any specific requirements or steps needed to perform for this release. You may, of course, just add it to the What's New section and leave this field blank. We won't show it if it's blank.
 +  - **Date Released** - the release date defaulting to today. You can change it here if you like, using the YYYY-MM-DD format. Note, if you change it to some date in the future it won't show up in the Plugin Store until that date.
 +  - **Server API** and **Bundle Versions** - retrieved from the ''Info.plist'' and just shown here for completeness. The Server API version is particularly important in that it determines what's shown as the minimum Indigo version required to use the plugin.
 +
 +Required fields are marked with an asterisk (*). Once you've filled out the form hit ''**Add Plugin**''.
 +
 +You'll notice that on the right side of the screen we've provided a quick cheatsheet for Markdown syntax. This will be helpful when editing any fields that allow Markdown.
 +
 +==== Editing a Plugin ====
 +To edit a plugin, just go to your Indigo Account's [[http://www.indigodomo.com/account/plugins|Plugin Contributions]] page, find the release in the list and click the ''**Edit**'' button. You'll be able to change all editable fields there.
 +
 +==== Adding a Release ====
 +When you have an update to a plugin, you just need to add a release to it. Go to the [[http://www.indigodomo.com/account/plugins|Plugin Contributions]] section of your Indigo Account, find the plugin, and click either the ''**Edit/Add Release**'' button for GitHub plugins or the ''**Add Release**'' button for directly managed plugins.
 +
 +=== Adding a GitHub Release ===
 +Adding a GitHub release couldn't be easier. Once you've clicked the ''**Edit/Add Release**'' button, you'll see the plugin edit form where you can edit the plugin and release information. At the bottom of the form, you'll see the following checkboxes:
 +
 +{{ :github_checkboxes.png?nolink |GitHub Checkboxes Image}}
 +
 +The first checkbox is automatically checked and therefore when you Save the form it will add any new releases. The next checkbox will update the main plugin description with the ''README'' file from the most recent release, and the last checkbox will update the icon from the most recent release. Super simple!
 +
 +**Note**: the release version number in the GitHub release source zip's Info.plist **must match** the tag for the GitHub release. Otherwise, the release will not be added. This sanity check will help ensure that you don't end up with version mismatches and the associated problems that will result (failed update checking, failed upgrades, etc).
 +
 +=== Adding a Release for a Directly Managed Plugin ===
 +Adding a new release this way isn't really very hard either, there are just a few fields you need to fill out:
 +
 +{{ :add_plugin_release_file.png?nolink&600 |Add Plugin Release File Image}}
 +
 +  - **Plugin ZIP File** - click the ''**Choose File**'' button and select the plugin folder. Note that Safari will automatically zip plugin folders before uploading (but your browser of choice may not).
 +  - ''**If there is an icon in the bundle, use it for the plugin's icon in the Plugin Store**'' - if checked then the icon in the bundle will replace the icon currently being used.
 +  - **Release Title*** - a short summary (100 characters max) of this release of the plugin.
 +  - **What's New*** - a full release description. This field may contain Markdown.
 +  - **Requirements** - an optional separate field that may contain Markdown. The intention of this field is to outline any specific requirements or steps needed to perform for this release. You may, of course, just add it to the What's New section and leave this field blank. We won't show it if it's blank.
 +  - **Date Released** - the release date defaulting to today. You can change it here if you like, using the YYYY-MM-DD format. Note, if you change it to some date in the future it won't show up in the Plugin Store until that date.
 +
 +Required fields are marked with an asterisk (*). Once you've filled out the form hit ''**Add Release**''.
 +
 +You'll notice that on the right side of the screen we've provided a quick cheatsheet for Markdown syntax. This will be helpful when editing any fields that allow Markdown.
 +
 +==== Editing a Release ====
 +To edit a release, just go to your plugin's detail page, switch to the Releases tab, expand the release you want to edit and click the ''**Edit**'' button. You'll be able to change all editable fields there.
 +
 +==== Icons and Branding ====
 +The Plugin Store shows icons for each plugin. If you don't include one in the plugin bundle (''Contents/Resources/icon.png'') and you don't add one explicitly to the release (see [[#Adding and Editing Releases]] for details) then the default Indigo Plugin icon {{:plugin_128x128.png?nolink&24|Plugin Image}} will be shown.
 +
 +To make it easy for users browsing the Plugin Store to identify something they're looking for, it's quite helpful to include an icon that represents what your plugin does. For instance, if you are integrating a specific vendor's products (like the Rachio Sprinkler example above) then you'll probably want to use their icon. Here are some tips to help find an appropriate icon:
 +
 +   * Many companies provide media links, including icons, that can be used for promotional purposes
 +   * Some do it as part of the developer API documentation (often under "marketing" or some such)
 +   * You can often find logos on their social media accounts in the photograph sections
 +
 +We believe that the vast majority of companies won't mind you using their logos to promote their products as long as it's clear that you have no direct affiliation to the company. If there is an issue it's easy for us to remove.
 +
 +Icon details: 256 x 256 is the optimal size. Images **must** be 128px high or they aren't going to look good (somewhat wider might work on some screen sizes). The icons must be .png files and the file name should always be ''icon.png''. Note the macOS Preview app can be used to convert other image formats to .png.
 +
 +==== Linking to Indigo Docs ====
 +If your documentation needs to link to Indigo's main wiki documentation then understanding how we handle documentation versioning is important. When we make major release changes that require significant documentation changes, we create a new wiki namespace for that release. For instance, the Indigo 6 docs are at:
 +
 +   https://wiki.indigodomo.com/doku.php?id=indigo_6_documentation:documents
 +
 +and the Indigo 7 docs are at:
 +
 +    https://wiki.indigodomo.com/doku.php?id=indigo_7_documentation:documents
 +
 +As an example, if Indigo 7.2 had significant enough changes that we decided to create a new namespace then they would be found at:
 +
 +    (https://wiki.indigodomo.com/doku.php?id=indigo_7_2_documentation:documents)
 +
 +and all references to previous (version 7) doc pages would now point to the old version. In order to help prevent this problem, you can use the following version-agnostic URL instead:
 +
 +    http://www.indigodomo.com/docs/PATH_TO_WIKI_DOC
 +
 +where PATH_TO_WIKI_DOC is everything after the colon (:) in one of the docs. So, for instance, if you want to link to the sprinkler controls:
 +
 +   (https://wiki.indigodomo.com/doku.php?id=indigo_7_documentation:overview#sprinkler_controls)
 +
 +but always want to link to whatever the latest docs are, you could instead use:
 +
 +   http://www.indigodomo.com/docs/overview#sprinkler_controls
 +
 +That url will attempt to map that wiki path (and optional anchor) to the most recent doc release. You may, of course, link directly to a specific version namespace doc if that is what is needed.
 +
 +==== A Few Final Thoughts ====
 +That's pretty much all there is to managing a plugin in the Plugin Store. Here are a few final random thoughts and important reminders:
 +
 +  * Putting your plugin on GitHub will encourage others to help you maintain the plugin. Wouldn't it be great if someone with a problem could actually fix it and submit a patch to you?
 +  * We highly recommend that you attach a zipped plugin (don't forget to delete the .pyc files) in your GitHub releases. When users click the Download Release button in the Plugin Store, it will download just the zipped plugin (not the entire repo). It'll be much clearer to users what they need to do next.
 +  * The GitHub wiki page is the best way to provide documentation (see the [[https://github.com/IndigoDomotics/rachio-indigo/wiki|Rachio]] and [[https://github.com/IndigoDomotics/alexa-hue-bridge/wiki|Alexa-Hue Bridge]] for good examples). The advantage to using the repo wiki is that others can help you maintain the documentation.
 +  * The most common way to provide support for a plugin (see //Help URL// above) is via our online forum. You can [[https://forums.indigodomo.com/viewtopic.php?f=121&t=7526 | request your own sub-forum]] and create topics (or children sub-forums) for each plugin.
 +  * You may not delete plugins or releases – if you need to for some reason just let us know and we'll handle it.
 +  * If you want to give someone else edit access (only edit, not add privileges) to your plugins, let us know and we can do that.
 +  * If you need to change a plugin from Directly Managed to GitHub or vice versa, let us know. It's a manually intensive process so it may take us a few days to get everything converted but we will do it for you.