Merge branch 'package-control'

Author: FichteFoll

CONTRIBUTING.md

@@ -182,10 +182,10 @@ I am text with a footnote[^1].
 
 ### Headings
 
-The page's title is specified in YAML front matter
-and is inserted into the rendered as a heading of level one.
+The page's title is specified in YAML front matter.
+You MUST start your document with a heading of level one.
 Any subsequent headings of the file
-MUST NOT be of heading level two or lower
+MUST be of heading level two or lower
 (where lower refers to the significance,
 not the numeric value).
 

docs/.vitepress/config.ts

@@ -135,6 +135,16 @@ export default defineConfig({
             { text: 'Syntax Definitions', link: '/guide/extensibility/syntaxdefs.md' },
           ],
         },
+        {
+          text: 'Package Control',
+          items: [
+            { text: 'Usage', link: '/guide/package-control/usage.md' },
+            { text: 'Troubleshooting', link: '/guide/package-control/troubleshooting.md' },
+            { text: 'Submitting a Package', link: '/guide/package-control/submitting.md' },
+            { text: 'Renaming a Package', link: '/guide/package-control/renaming.md' },
+            { text: 'Utilities for Packages', link: '/guide/package-control/utilities.md' },
+          ],
+        },
         {
           text: 'Example Setups',
           link: '/guide/example-setups/',
@@ -162,6 +172,15 @@ export default defineConfig({
             { text: 'Mouse Bindings', link: '/reference/mouse_bindings.md' },
             { text: 'Menus', link: '/reference/menus.md' },
             { text: 'Metadata', link: '/reference/metadata.md' },
+            {
+              text: 'Package Control',
+              items: [
+                { text: 'Channels and Repositories', link: '/reference/package-control/channels-repositories.md' },
+                { text: 'Channel.json', link: '/reference/package-control/channel.md' },
+                { text: 'Repository.json', link: '/reference/package-control/repository.md' },
+                { text: 'Reviewing', link: '/reference/package-control/reviewing.md' },
+              ],
+            },
             { text: 'Plugins', link: '/reference/plugins.md' },
             { text: 'Projects', link: '/reference/projects.md' },
             { text: 'Python API', link: '/reference/python_api.md' },

docs/guide/example-setups/typescript.md

@@ -8,7 +8,7 @@ over the other options for ST3 listed [below](#options-for-sublime-text-3).
 
 This built-in TypeScript package primarily provides syntax highlighting
 and is accompanied by the Sublime Text core features,
-such as [completions](../extensibility/completions.html)
+such as [completions](/guide/extensibility/completions.md)
 and [“Go to Definition”](https://www.sublimetext.com/docs/indexing.html).
 
 ### LSP

docs/guide/extensibility/plugins/input_handlers/index.md

@@ -418,7 +418,7 @@ You may find that another works better for you.
 ## Code Archive
 
 The final code examples presented on this page
-[are included in the source git repository][code].
+[are included in the source Git repository][code].
 You can download a [zipball][] of it (via [DownGit][])
 and extract it into your Packages folder
 to experiment with them.

docs/guide/package-control/renaming.md

@@ -0,0 +1,79 @@
+---
+title: "Package Control: Renaming a package"
+---
+
+<!-- Originals: -->
+<!-- https://packagecontrol.io/docs/renaming_a_package -->
+<!-- https://github.com/wbond/packagecontrol.io/blob/master/app/html/docs/renaming_a_package.html -->
+
+# Renaming a package
+
+Let's guide you through the process of renaming a package in the [default Package Control channel][pcc].
+
+The goal is to update the main channel so that your entry:
+
+- gets its new `name`
+- is sorted alphabetically
+- has its previous name in the array of `previous_names`
+
+The `previous_names` will ensure Package Control
+is able to move existing installations over to the new name smoothly.
+Don't forget to update your documentation, menu, and command palette entries
+to also have the same new name.
+
+
+## Review the new name
+
+Read the [naming guidelines][naming] to make sure your new name will work.
+
+[naming]: ./submitting.md#pick-a-name
+
+
+## Fork the channel
+
+1. Fork the [Package Control channel][pcc].
+2. Clone your fork to your machine.
+3. Open it with Sublime Text.
+
+
+## Update the repository
+
+1. Remove your package entry from its old location.
+   It will be in one of the JSON files
+   in the `repository` sub-folder.
+2. Paste the package entry into the correct JSON file
+   based on the new name.
+   We keep package entries alphabetized
+   to reduce conflicts when merging pull requests.
+3. Update the `name` key with the new name.
+4. Add a `previous_names` key to the top-level JSON structure for your package.
+   `previous_names` needs to be an array of strings.
+
+
+### Example
+
+```json
+    {
+        "name": "AlignmentPlus",
+        "previous_names": ["Alignment"],
+        "details": "https://bitbucket.org/wbond/sublime_alignment",
+        "releases": [
+            {
+                "sublime_text": "*",
+                "tags": true
+            }
+        ]
+    }
+```
+
+
+## Submit a Pull Request
+
+Now you're ready to commit and push your changes
+and make a PR on the [Package Control Channel][pcc] repository.
+Follow any guidelines there and make sure the tests pass!
+
+Note that this is a community project
+and people review PRs in their spare time; it might take a while.
+
+[pcc]: https://github.com/wbond/package_control_channel

docs/guide/package-control/submitting.md

@@ -0,0 +1,223 @@
+---
+title: "Package Control: Submitting a package"
+---
+
+<!-- Originals: -->
+<!-- https://packagecontrol.io/docs/submitting_a_package -->
+<!-- https://github.com/wbond/packagecontrol.io/blob/master/app/html/docs/submitting_a_package.html -->
+
+# Submitting a package
+
+One of the reasons developers love Sublime Text
+is because of the unmatched breadth and quality of the package ecosystem
+and community.
+Package Control is the community project that helps users find,
+install, and update 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.
+
+
+## Review existing packages
+
+Start by looking for similar packages you might be able to contribute to.
+
+We strongly encourage improving or adding to existing packages.
+This means that packages are of higher quality,
+and users don't have to choose from several similar options.
+We regularly replace packages that have become outdated
+with newer implementations.
+
+
+## Pick a name
+
+Beyond taste there are some technical aspects to keep in mind
+when naming your package.
+A package is a directory, so the name must be safe for use in that context.
+And a package is (often) a Python module,
+meaning Python needs to be able to load it properly.
+Also think about how users will be able to search for your package:
+you don't want users to have to type in special characters or diacritics,
+to be able to find it.
+
+Some rules to follow:
+
+- 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
+  (README etc.) though of course.
+- Don't use a name too similar to another: we don't want Todo and T0d0.
+- Don't use snake_case.
+  There are minor technical reasons to avoid that,
+  but mostly it's just very uncommon (in other words, it looks weird).
+- Don't use a `.` in the package name.
+  If your package includes any Python code, it will not load in Sublime Text.
+  This is because Python uses . as a folder separator when importing code.
+- Don't use a `/` or other restricted characters in the package name.
+  Invalid characters include:
+  `<`, `\>`, `:`, `"`, `/`, `\`, `|`, `?` and `*`.
+- Use ASCII only.
+- Language support (aka "syntax" or "grammar") packages
+  are named after the language it supports,
+  without suffixes like "syntax" or "highlighting".
+
+Note that the package name is used in references to resources,
+for instance settings files.
+If your package name is different from its Git repository name,
+make sure you rename the local clone to match.
+
+
+## Decide how to host
+
+Pick one of the following two hosting options:
+
+- A public GitHub, Bitbucket or GitLab repository.
+  Only include one package per Git repository
+  and be sure the root of the package is the root of the repository.
+  Do not include a packages.json file in your 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.
+  Also see the [repository.json documentation][repo].
+
+When using a public Git repository,
+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][semver].
+
+If you chose self-hosting,
+you will need to use semantic versioning in your `packages.json` file.
+
+
+## Prepare your Git repository
+
+- Create a [semver-numbered][semver] tag.
+- Ensure there are no `.pyc` files in your repository.
+- Remove `package-metadata.json`.
+  This is automatically generated by Package Control
+  when a package is installed
+  and should not be in your repository.
+- Check file names for cross-platform compatibility,
+  the same restricted characters apply as in your package name.
+- Under very specific circumstances,
+  like including executables or shared libraries,
+  add a `.no-sublime-package` file to the root of your repository.
+  This file will prevent Package Control from shipping your package
+  as a zipped `.sublime-package` file.
+  It is not needed for bundling Python modules.
+  If a module uses numerous absolute imports
+  to import parts of itself
+  and an addition to `sys.path` is necessary,
+  this also works if the package is archived
+  because of Python's internal ziploader.
+
+
+## Add your Git repository to the default channel
+
+Fork the [Package Control Channel][pcc]. Then:
+
+- For packages hosted on a public GitHub, Bitbucket or GitLab URL,
+  add your package information to the correct file in the repository directory.
+  For full details of the possibilities,
+  please refer to the [repository.json documentation][repo].
+- For self-hosted packages
+  add the URL of your repository JSON file to the `channel.json`
+  in the root directory.
+
+
+## Submit a pull request
+
+Now you're ready to push your changes and make a PR
+on the [Package Control Channel][pcc] repository.
+Follow any guidelines there and make sure the tests pass!
+
+For a cleaner process,
+you should only submit one package per PR.
+This allows package submissions to be reviewed and merged independenly.
+
+Note that this is a community project
+and people review PRs in their spare time;
+it might take a while.
+
+[repo]: /reference/package-control/repository.md
+[pcc]: https://github.com/wbond/package_control_channel
+
+
+### LSP and SublimeLinter
+
+Plugins for the LSP or SublimeLinter frameworks should be submitted to the repositories where those teams manage related packages:
+
+- Linter packages should be submitted over at [SublimeLinter][sl].
+- Similarly, any language server protocol packages
+  are managed via [SublimeLSP][lsp].
+
+[sl]: https://github.com/SublimeLinter/package_control_channel
+[lsp]: https://github.com/SublimeLinter/package_control_channel
+
+
+
+### Things that help your submission get approved more quickly
+
+- We only accept submissions from maintainers of the package being submitted.
+- A valid [semver][] numbered tag must exist on the repository.
+- Ensure the README clearly describes the purpose of the package
+  and how to use it.
+- We strongly advise against adding features to the context menu in most cases,
+  because space in this menu is very limited.
+  In any case,
+  features should apply to the specific context,
+  their visibility should be conditional,
+  and preferably configurable.
+- We strongly advice against adding keybindings by default.
+  There aren't enough keys for all packages,
+  so you risk overriding those of other packages.
+  Instead, provide commented out suggestions in a keymap file,
+  and/or explain how to create bindings in your README.
+- Ensure preferences and keybindings (if any)
+  are listed in the menu and the command palette,
+  and open in split view (i.e. using `edit_settings`, not `open_file`).
+- Language support packages should not ship with color schemes
+  to specifically support the language.
+  Please review common [scope names][scopes]
+  that will allow any color scheme to support your language.
+- Note that the [`git-archive`][arch] feature is used to create the package file,
+  meaning you can use [`.gitattributes`][attr] to exclude images and other files
+  that have no functionality in the package
+  (typically drastically reducing file size of your package
+  when images are included in the repository).
+
+[scopes]: https://www.sublimetext.com/docs/scope_naming.html
+[attr]: https://www.git-scm.com/docs/gitattributes#_export_ignore
+[arch]: https://git-scm.com/docs/git-archive
+
+
+### What labels to use
+
+For labels, please follow these recommendations:
+
+- Labels are always in lowercase.
+- Packages that provide ...
+  - a [language syntax][syntax] have the "language syntax" label.
+  - (the colors for) [syntax highlighting][colors]
+    have the "color scheme" label,
+    whereas packages that provide [theming for the UI][theme]
+    have the "theme" label.
+  - a [build system][build] have the "build system" label.
+  - [snippets][snip] have the "snippets" label.
+  - [completion metadata][complete] have the "completions" label.
+  - any other kind of auto-complete have the "auto-complete" label.
+  - formatters have the "formatting" label,
+    and optionally "prettify" or "minify", if appropriate.
+  - utilities have the "utilities" label.
+
+[syntax]: https://www.sublimetext.com/docs/syntax.html
+[colors]:https://www.sublimetext.com/docs/color_schemes.html
+[theme]: https://www.sublimetext.com/docs/themes.html
+[build]: https://www.sublimetext.com/docs/build_systems.html
+[snip]: https://www.sublimetext.com/docs/completions.html#snippets
+[complete]: https://www.sublimetext.com/docs/completions.html#completion-metadata
+
+[semver]: http://semver.org