Better plugin bootstrapping support

[pykong]

In this THREAD on the Sublime forum I suggest a plugin for bootstrapping new plugins. @FichteFoll asked me to open an issue here instead.

The functionality which I believe would greatly benefit, especially newcomers to plugin development is to have a more comprehensive boilerplate of code, exemplifying and encouraging best practices.

The current boilerplate plugin is just a single class in a single file.

A more comprehensive boilerplate should at the very least contain:

• a settings file
• keybinding files for all three platforms
• a command file
• a menu file for the Preferences > Package Settings submenu*

in the preparation of a push to GitHub these additional files might also be added:

• LICENSE (MIT)
• .gitignore

(* Best practices would dictate that default and user settings/keybinding files are opened in parallel in a new two columned window, as sublime settings itself do. It is indeed very annoying that many plugins require opening default and user files separately. )

Also importantly these files would be placed in a folder with the named after the project (could be prompted for before creation). This folder is to be located under /Packages/ not under /Packages/User/ as it is currently the case with new plugin files. This is important to keep the user folder clean and not overrun with orphaned plugin files.

[FichteFoll]

Note that I don't intend to provide boiler plate like this because there are differen types of packages requiring different files. There are:

• pure plugin packages (maybe with a settings file)
• pure syntax definition(s) packages
• pure snippets/completions packages
• a combination of all

Besides, I'm not a huge fan of suggesting everyone to provide a default key bindings file for their package. Sometimes they are useful and required, e.g. for vim emulation or in order to replace built-in functionality like "Duplicate Lines", and sometimes they are just arbitrary bindings that the author deemed useful but conflict with other packages, where the author had the same idea.

What I would like to do instead is have a command that creates a package, opens it in a new window and then probably open the command palette with pre-inserted "PackageDev: New" text, so that it filters all the already existing commands to create resource files (with boilerplate). The user may then choose an item depending on what is needed and is shown how they can create more files when needed.

Even a readme and license file I find too suggestive because one may prefer the GPL over MIT or would prefer writing the readme in reStructured Text (albeit this is quite rare, as markdown seems very prevalent in this area).

The current boilerplate plugin is just a single class in a single file.

Is there anything else you'd expect to be in the boilerplate for a new plugin? (Also note that PackageDev doesn't offer a command to create a plugin, currently.)

[pykong]

@FichteFoll Your points are all valid. I believe it is a somewhat philosophical question. Do we want to enforce some conformity to unify the user experience, or allow a more laissez faire ecosystem. If the former is the case my suggestion may be helpful, in the latter case certainly not.

Still, the suggestion to place new plugins automatically in an own, respectively named, folder under /Packages/ holds valid. It is a minimal but still meaningful improvement of the status quo.

Otherwise, there are no other files I like to have included in the plugin.

[FichteFoll]

Still, the suggestion to place new plugins automatically in an own, respectively named, folder under /Packages/ holds valid. It is a minimal but still meaningful improvement of the status quo.

Yes, this is actually the main reason I wanted you to create this issue. If there is some more discussion about it, all the better.

I'll implement this functionality when I find the time (not before two weeks) and see how it works out. The current templates can be found here, btw: https://github.com/SublimeText/PackageDev/blob/master/plugins_/new_resource_file/templates.py A menu template needs to be added still.

[r-stein]

What do you think about a guided dialogue as you have it if you create a new eclipse/IntelliJ project:

input panel

Package Name: [|]

quickpanel

What type of package you want to create?
- python package
- syntax package
- empty package
- ...

...Based on the selection above...

yes-no-cancel dialog

Do you want to create a commands file? (PackageName.sublime-commands)
This will provide commands for the quick panel.
- yes/no/cancel

yes-no-cancel dialog

Do you want to create a keybindings file?
- yes/no/cancel

quickpanel

Which license to you want to add?
- None
- MIT
- GPL

[FichteFoll]

I thought about that briefly. I'll consider it for a later time once I am through with the initial plan.

Though at this point we're probably slowly going out of PC's scope imo, with the license thing at least. The other parts are still ST-package-specific.

[pykong]

@FichteFoll

Is there anything else you'd expect to be in the boilerplate for a new plugin?

I forgot a project file with the plugin folders path added already. I feel this rather is unintrusive but starting the plugin development as a project right away is helpful.

[FichteFoll]

Added a command to create a new package in ab5ced4e91de9b6b2dd27e2b894dd2888ddf6274. It opens a new window with the created folder added to the project and prompts for resource files to be created via the command palette.

Let me know how this works out for you.

[pykong]

@FichteFoll Nice. I will have a look into it on the weekend and let give you my honest feedback. Thank you for your work so far.

[pykong]

@FichteFoll I believe this is a very good start. PackageDev: New Package prompts for package name, then creates a new folder under Packages/ and opens a new window. It also opens the command palette (/quick panel?) prefilled with other PackageDev commands to populate the package with other files.

First, I want to mention that the mere placement of the new package in its own folder, not just as a stray python file in the user dir is a great improvement over the default pendant of ST. As discussed previously I consider this a big stride towards a cleaner plugin system.

Yet, I miss any integration of the new package command with the rest of functionality. For example:

• Upon running the new settings file command a new settings file with the prefix Preferences or the PackageName should be automatically saved to the package folder. Currently only an unnamed buffer is created.
• The package folder created is initialized completely empty. Shouldn't at least a basic python plugin file placed inside it? This goes back to our discussion what if any boilerplate code should be there upon initialization.
• Instead of a default boilerplate, the user could be prompted for what files he likes to include. This would require asking the user for files to include with the PackageDev commands until he decided to exit this input loop.

I like what you did, yet see it as a mere starting point.

BTW - The way PackageDev handles settings is outstanding! Not only is there just a single menu entry settings, which opens both Default and User preferences juxtaposed in a new window with a two column layout. But the "pencil phantom" to transfer settings from the Default to the User file is so useful! Sublime Text should enforce such settings handling as the default. At least any new settings file created with PackageDev should follow this UX scheme.

Tell me if you need any more information or ask if you need clarification on any point.

[keith-hall]

The package folder created is initialized completely empty. Shouldn't at least a basic python plugin file placed inside it?

I vote no, sometimes people want to create a package without a plugin file. Indeed this wouldn't be necessary if your input loop prompt idea was implemented.

About the dual column layout for settings, yeah maybe an entry in the command palette to create the relevant sublime-menu file would be useful, or have it tie into the new preferences file functionality automatically somehow.

[r-stein]

I think something like a creation "wizard" as you have it if you create a project in eclipse or IntelliJ would be nice. Maybe an quickpanel with the following entries (the package is called MyPackage) (- separates the two rows):

Empty - 
Simple Python Package - my_package.py
Full Python Package - my_package.py, Main.sublime-menu, MyPackage.sublime-settings, ...
Syntax Definition - MyPackage.sublime-syntax
ColorScheme - MyPackage.tmTheme
Sublime Theme - MyPackage.tmTheme, MyPackage.sublime-theme
...

Or it could ask for each file type (I wouldn't ask for theme files, because they are not so common)

[FichteFoll]

I'll add a template for menu files (similar to the "more complex" commands file, which also includes this).

Still undecided about the wizard. Will most likely not make it into 3.0.0, either way.

[pykong]

@FichteFoll What is your idea, on the other points I mentioned? Especially the input loop and automatic naming of views?

[FichteFoll]

@bfelder

It also opens the command palette (/quick panel?) prefilled with other PackageDev commands to populate the package with other files.

Yes, this is indeed the command palette.

Upon running the new settings file command a new settings file with the prefix Preferences or the PackageName should be automatically saved to the package folder. Currently only an unnamed buffer is created.

I'm against automatically saving files, because authors may prefer to save them with a different name or in a different folder. I like that you have to explicitly save a file, which allows you to modify the files final location. It also doesn't do "permanent" alterations of the package folder when the user might not expect it. That said, I added heuristics to set a default file name for the unnamed view where it makes sense.

The package folder created is initialized completely empty. Shouldn't at least a basic python plugin file placed inside it? This goes back to our discussion what if any boilerplate code should be there upon initialization.

As @keith-hall, I'm against this and would rather do the other option of providing a wizard.

Instead of a default boilerplate, the user could be prompted for what files he likes to include. This would require asking the user for files to include with the PackageDev commands until he decided to exit this input loop.

This is what I referred to when I said "wizard". I haven't decided on this yet, but it won't come in 3.0.0.

Sublime Text should enforce such settings handling as the default. At least any new settings file created with PackageDev should follow this UX scheme.

I added a commands template that had the required commands prefilled, but it wasn't accessible in the commands file. So I fixed that and additionally added a menu template with these commands as well. And finally, all occurences of a package name inside a snippet are now replaced with the automatically determined package name, if available. Gotta say, this feels pretty good!

---

I'll have another release candidate (the last, hopefully) with this up within the next hour and will start working on a readme update for the stable release.

[FichteFoll]

Honestly, I'm quite happy with the current situation of the "New * File" commands and templates. They are granular and allow a flexible usage for package authors where they can add resource files however they want and under whatever file name they want.

If someone still feels like a wizard or package skeletons would be useful, please consider:

1. The target audience, i.e. how knowledgeable they are about ST packages and how a wizard would help them (or make things worse).
2. What kind of skeletons would be useful in which situations and which of them should be suggested/included by PD.
3. Whether a wizard would be faster than just creating the files with the "New * File" commands.

[pykong]

New files are now created with awareness to the current project/folder. (i.e. file names and contents are pre-populated with the project name/paths where required.) Having used PackageDev over the last couple month, I feel this feature alleviates the need for a wizard, as I have initially proposed.