Docs

Submitting a Package

One of the biggest reasons developers love Sublime Text is because of the package ecosystem that has developed. Package Control not only helps to make installing packages easier, but also has the goal of indexing all of the available packages.

If you’ve taken the time to develop a package, please consider adding it to the default Package Control channel so users can easily install and keep your package up-to-date.

1. Reviewing Existing Packages

1. Visit the Search page and look for similar packages.
2. Try to improve an existing package before adding another. When possible we strongly encourage working with an existing package maintainer to add functionality or tweak a package rather than proliferating lots of very similar options. This is especially true if your package is very simple.

2. Pick a Name

• Try not to use the word Sublime in your package name. Every package available via Package Control is for Sublime Text. Using the word Sublime just adds noise to the list when trying to find packages. You can use the word Sublime in your marketing material, but omit it the package list, e.g. Sublime SFTP.
• Don’t use a name too similar to another. We don’t want Todo and T0d0.
• Use CamelCase or underscore_notation. Other Python packages in ST3 will be able to more easily interact with it. Additionally, the search indexer will properly split words, making search results more accurate. Obviously this does not matter if your package name is a single word or contains no Python.
• Do not use a . in the package name. If you package includes any Python code, it will not load in ST3. This is because Python uses . as a folder separator when importing code.
• Do not use a / or other restricted characters in the package name. Package names are used as part of a file or folder name, depending on what version of Sublime Text the user is using. Invalid characters include: <, >, :, ", /, \, |, ? and *.
• Use ASCII only if possible. The quick panel that Package Control uses in Sublime Text for selecting packages does not do match characters with diacritics unless they are entered by the user. Thus a user searching for resume will not find résumé.
• Check hard-coded references. The package name is (effectively) used as the package folder name. Any file path references in a theme or Python code must use this package folder name. Be sure your local package folder name matches. See the .no-sublime-package file discussed in step 5 if you need to ensure files are always unpacked into a folder.

3. Decide how to Host

You‘ll need to pick one of the following two hosting options:

• Use a public GitHub or BitBucket repository. Only include one package per repository and be sure the root of the package is the root of the repository.
• Host .sublime-package files and a packages.json on a web server with SSL. For each release you’ll need to create and upload a new package file and update the packages.json information. Hosting of the files must be done on a secure server to help ensure the security of users’ machines. Unsecure URLs could lead to malicious code being loaded and run. This is rarely used – see example-repository.json for documentation.

No matter how your package is hosted, Package Control will check it for updates approximately once per hour. The Last Seen date on the package detail page of this site will show the last time (UTC) when the package information was refreshed.

4. Pick a Versioning Strategy

If you are using GitHub or BitBucket for your hosting, you will need to create a tag each time you want to make a new version available to users. The tag names must be a semantic version number.

Please note that branch-based releases have been deprecated and no new packages will be accepted that utilize that feature. Existing packages are encouraged to update to using tags.

If you chose manual package hosting, you will need to use semantic versioning in your packages.json file.

5. Prepare Your Repository

1. Remove any .pyc files from your repository. Sublime Text will generate the appropriate .pyc files the first time the package is loaded. Also, different versions of Python use different formats.
2. Remove package-metadata.json. This is automatically generated by Package Control when a package is installed and should not be in your repository.
3. Check file names. Windows has the most restrictive rules on valid characters in a file name. Be sure file names do not contain characters including: <, >, :, ", /, \, |, ? and *. Non-ASCII characters may present trouble when developing cross-platform packages.
4. If including executables or shared libraries, add a .no-sublime-package file. Adding this file to the root of your repository will prevent Package Control from keeping your package packed as a .sublime-package file in ST3.

6. Add Your Repository to the Default Channel

1. Fork the Package Control Channel
2. Clone your fork to your machine
3. Open the package_control_channel/ folder with Sublime Text

4. Add package info based on the type of hosting:

   • GITHUB/BITBUCKET HOSTING: Add your package info to the proper JSON file in repository/ folder.

     Example of GitHub hosting:

     {
     	"name": "Alignment",
     	"details": "https://github.com/wbond/sublime_alignment",
     	"releases": [
     		{
     			"sublime_text": "*",
     			"tags": true
     		}
     	]
     }

     Example of BitBucket hosting:

     {
     	"name": "Alignment",
     	"details": "https://bitbucket.org/wbond/sublime_alignment",
     	"releases": [
     		{
     			"sublime_text": "*",
     			"tags": true
     		}
     	]
     }

     For other options, please read the documentation in the example-repository.json file. Please note that the version, url and date sub-fields are not allowed in the centralized channel. If you wish to use these, you must host your own packages.json.

   • MANUAL HOSTING: Add the URL for your packages.json file to channel.json. See example-repository.json for documentation about the structure of the packages.json file.

5. Add the platforms key to your releases if necessary.

   • Package that only works on Mac and Linux

     {
     	"name": "Alignment",
     	"details": "https://github.com/wbond/sublime_alignment",
     	"releases": [
     		{
     			"sublime_text": "*",
     			"platforms": ["osx", "linux"],
     			"tags": true
     		}
     	]
     }

   • Package that only works on Windows

     {
     	"name": "Alignment",
     	"details": "https://github.com/wbond/sublime_alignment",
     	"releases": [
     		{
     			"sublime_text": "*",
     			"platforms": ["windows"],
     			"tags": true
     		}
     	]
     }

7. Run the Tests

1. Install the ChannelRepositoryTools package via Package Control.
2. Run the ChannelRepositoryTools: Test Default Channel command from the command palette and ensure the tests pass.

8. Submit a Pull Request

1. Browse to your fork on github.com
2. Click on Pull Requests in the right-hand nav and click New Pull Request
3. Enter a description in the Title field
4. Click the Create pull request button

Please be patient as your pull request is reviewed. We review changes to try and help prevent duplicate packages, spot common errors and help improve the package experience for users.