ctrl+shift+p filters: :st2 :st3 :win :osx :linux
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

3. Decide how to Host

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

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 troublesome 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 OS X 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.