Skip to content

Package checks

Jump to bottom
FichteFoll edited this page Jan 4, 2017 · 5 revisions

This document explains the failures and warnings reported by the review tool regarding the package itself and how to resolve these.

Failures and warnings are grouped by their type and by what they are complaining about. Their messages are used as headings and {} represents a placeholder.

Table of Contents

Failures

Key Bindings

The binding {} unconditionally overrides a default binding

Key bindings from packages should not override any default bindings, unless they specifically intend to replace the default action.

An example for this would be a package whose main feature is changing how pasting of multiple lines with multiple selections behaves.

Binding is missing the keys {}

A key binding must at least contain the keys and command keys.

See here for documentation.

'keys' key is empty or not a list

Each key binding must contain a keys key, which is a list of key chords.

See here for documentation.

Invalid key '{}'

The key used in the key binding is not valid. Valid keys are any visible character and those listed here.

This check is not 100% accurate, so if you believe the key is valid, report this as an issue on the package_reviewer repo.

Invalid modifier key '{}'

Valid modifier keys are: super, ctrl, option (= alt), alt and shift.

Package Control

'package-metadata.json' is supposed to be automatically generated by Package Control during installation

This file is absolutely redundant and should never be submitted to a version control. It shouldn't even exist inside a package that was not installed by Package Control at all.

messages folder exists, but messages.json does not

A messages/ folder usually indicates an intent to use the messaging feature of Package Control. For this, however, a messages.json file in the package root is required. You can read more at the docs.

unable to load messages.json

The messages.json file must be a valid JSON document. Unlike configuration files, this means that neither comments nor trailing commas are allowed.

Read the exception message included in the report for more details about why the file couldn't be loaded.

Key {} is not 'install' or a valid semantic version

All keys of the messages.json file must be either "install" or a semantic version string. Refer to the docs for details.

File '{}', as specified by key {}, does not exist

Entries in the messages.json mapping need to be relative file paths and point to a file that exists inside the repository.

Other Resource files

'.pyc' file is redundant because its corresponding .py file exists

.pyc files are cached binary files created by Sublime Text when compiling plugins. ST2 places these next to the source file, but as long as the source file itself exists, it is redundant to add these to version control. Remove them from the repo and add *.pyc to your .gitignore.

'.cache' file are redundant and created by ST automatically

Same situation as for .pyc. ST2 creates cache files for property lists, which are entirely redundant to submit to version control. Remove them from the repo and add *.cache to your .gitignore.

Invalid JSON (with comments)

Invalid Plist

Invalid XML

These three errors are the result of a resource file being unparsable. Check the corresponding exception message for more information on how to resolve the issue.

The package contains {} Python file(s), but none of them are in the package root [...]

[...] and no build system is specified.

Python plugins must be placed in the package's root, which equals to the repository root. Check if you accidentally placed your plugins in a subfolder.

The package does not define any file that interfaces with Sublime Text

Are you sure this is a Package for Sublime Text?

'.sublime-package' files have no business being inside a package

Package Control will download a snapshot of the repo and use that as base for creating a '.sublime-package' archive on the user's machine.

'.sublime-workspace' files contain session data [...]

[...] and should never be submitted to version control

As mentioned in the message, these files should never be shared with anyone or anything and immediately added to your *.gitignore. Take a look for yourself.

Warnings

Resource Files

The binding {} is also defined in default bindings but is masked with a 'context'

Package bindings can override default bindings in certain situations for various reasons. Because we cannot possibly analyze this automatically, this warning exists to suggest a human audit over a package's bindings.

It is not advised to specify mousemaps [...]

[...] because of how limited the configuration options are. Instead, suggest the user to add specific bindings to their User package.

Unlike keymaps, mousemaps do not accept a context restrictor and are thus always active. In order not to create conflicts with other packages (and the built-in bindings), do not define bindings by default and let the user manage them instead.

'.sublime-syntax' support has been added in build 3092 [...]

[...] and there is no '.tmLanguage' fallback file

In your sublime_text version selector, you should write that the package requires at least build 3092 because it defines a .sublime-syntax file without a .tmLanguage replacement file for older builds in place.

Because package_reviewer does not look at the repository submission, this might be a false positive.

Package Control

'.no-sublime-package' is defined. Please verify that it is really necessary

The .no-sublime-package file tells Package Control to extract your package and store it in the Packages instead of the Installed Packages folder. This has the disadvantage that a user can not easily override only parts of a package anymore and should thus only be done when it is essential for the package to work.

The .no-sublime-package file is only needed if (ordered by frequency of occurrence):

  • The package executes binaries included in the package itself using the subprocess module in Python plugins or a build system.
  • The package runs scripts included in the package using an external application, such as node.
  • The plugin code loads binary Python modules.
  • A bug in Sublime Text prevents a certain feature from working if in archived state (none known currently).

It is not needed for bundling Python modules. Relative imports work just fine in Sublime Text 3

For reading files from the package within a Python plugin, use the sublime.load_resource API. For storing data in files, consider using the User package or ST's cache folder (sublime.cache_path()).

This check is not 100% accurate and the actual need can be debated.

'.no-sublime-package' is defined, but no other resource file can make use of it

It is even more unlikely that a package needs to be unextracted when it defines neither a plugin nor a build system.

See the warning description above for more.

Clone this wiki locally