If you don’t follow these directions, your package will probably take an extra 7-14 days to get included!
Host your plugin in its own repository on GitHub or BitBucket.
Only include a single plugin, and have the plugin files in the root of
the repo.
Do not include package-metadata.json in your repository. This file is created on each client machine to track what version of a package is installed. To customize the description of your package, do so using the description field on GitHub or BitBucket. The version is derived from the last commit date. If you want to semantially version your package, please see Channels and Repositories and read about creating a custom packages.json file. If you are hosting on GitHub, there is a step-by-step guide.
Please add it in alphabetical order to help prevent conflicts. Do not include .git at the end of the URL.
Add a mapping to the package_name_map key. This is necessary if you are not using a custom packages.json file and the URL slug of your GitHub repository is not the desired name for the package. BitBucket repositories use the repository name, so there should not need to be any mapping performed.
If your package contains the word Sublime in it, consider mapping it to a name without Sublime for the sake of reducing noise. This mapping just removes the word from the community package list, the install list (in Sublime) and from the folder that will contain the package.
Make sure you commit does not change every line in the file. This means you changed the line endings or indentation. You'll need to do a fresh commit that only changes a couple of lines.
Channels are JSON files hosted on a URL that contains a list of repository URLs. See example-repositories.json for the format. When a user requests to install a package, their channels are queried for a list of repositories.
By default, a single channel is included with Package Control, http://sublime.wbond.net/repositories.json. The only reason to create another channel is if you want to create a private distribution for a closed group of people.
Repositories are JSON files hosted on a URL that contain a list of packages. See example-packages.json for the format. The custom format allows specifying platforms (windows, osx, linux) for packages and provides a description and version.
You can see a version of a packages.json file at http://sublime.wbond.net/packages.json. If you create your own packages.json file, follow steps 2–5 of Submitting a Package, just add the URL of your JSON file.
In addition to supporting a custom JSON format for repositories, Package Control supports GitHub and BitBucket URLs:
With these URLs, no work is necessary by the package developer to support Package Control. Package Control parses JSON from the GitHub and BitBucket APIs and uses their zip download functionality to fetch the package.
There is an option package_name_map in the settings to allow for mapping repository names to package names. For instance, the sode-theme repository on GitHub needs to be installed as Theme - Soda to function properly. Channels may also specify name mapping.
You’ll need to create a custom packages.json file if any of the following is true:
If you want to learn about the details of the channel/repository system, please see Channels and Repositories. If you just want to provide a custom packages.json, keep reading.
The best practices for maintaining a custom packages.json include:
To add your own packages.json to the default Package Control channel, do the following:
{
"schema_version": "1.2",
"packages": [
{
"name": "Your Package Name",
"description": "The description of your package",
"author": "Your name or github username",
"homepage": "https://github.com/your_github_username/your_repository_name",
"last_modified": "2011-12-12 05:04:31",
"platforms": {
"osx": [
{
"version": "1.1.0",
"url": "https://nodeload.github.com/your_github_username/your_repository_name/zip/your_tag_name_here"
}
]
}
}
]
}
https://raw.github.com/your_github_username/your_repository_name/master/packages.json
Please be aware that by default, Package Control will automatically upgrade all packages every time the editor is started. If you are editing a package that anyone other than yourself is committing to, you should use Git or Hg to initially clone the repository instead of using the Install Package command.
If you clone a repository, Package Control will use the VCS to pull down and merge updates, insteading of overwriting your edits with the latest version. The exact commands that are used to pull down and merge changes can be configured via the settings.
If you do ever find yourself in a situation where your edits to a package were overwritten by Package Control, you can find a backup copy in the Backup folder. This folder can be located by selecting the Preferences > Browse Packages… menu and then browsing up a folder. Backups are stored in timestamped folders.
When creating a package, it is possible to show users a message when the package is installed, and also after upgrades. To do this a file named messages.json must be included in the root directory of the package. The example-messages.json file shows the proper structure of the json. Each value will be a file path that is relative to the package directory. Each key will either be the string install or a version number.
When a package is installed, if the key install is present in the messages.json file, the value will be used as the file path to a txt file containing a message to display the users.
When a package is upgraded, Package Control looks through each key in the messages.json file and shows the content of the text file that is a value of any key that is higher than the previous version of the package the user has installed. Thus if the user had version 1.1.0 installed, the txt files for 1.2.0 and 1.1.1 would be shown. If the user had version 1.1.1 installed, only the messages for version 1.2.0 would be shown.
If you are developing a package, and plan on doing custom repository hosting instead of using GitHub or BitBucket, Package Control includes a command to create a .sublime-package file for you from one of your package directories.
Run the Create Package command and you can select what package you would like to create a package file for. The packager exlcudes various VCS metadata, Sublime Text 2 cache files and .pyc files by default. The list of excluded files can be tweaking through the settings.