Plugin best practices
A collection of tips how to structure, name, tag, describe and promote your plugin
Now that you have learned a lot about plugins and have decided to start developing your own, here are some best practices that will make it easier for users to find and use your plugins, and also for you to maintain it and maybe even understand your own code later on 😉.
Plugin with own classes
Basic Panel plugin
Panel plugin with components
For more complex plugins, add other subfolders as required.
Comments help you and your users to understand your code even years later and they make it easier for other developers if they want to contribute to your plugin's development. Documenting comments will allow you to auto-generate documentation of your classes and methods (where applicable).
While you are free to name your plugin whatever you like, it makes sense to give your repo a name that immediately makes it clear that your plugin is for the Kirby CMS. Most developers name their repos
The plugin name itself ideally reveals the purpose of the plugin.
Add a good description to your plugin repo so that people looking for a specific plugin will immediately get what the plugin actually does.
On GitHub, you can tag your plugins. Don't forget to add the following tags in addition to those that describe the purpose of your plugin:
Use semantic versioning:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes
Add a composer.json file with basic information about your plugin, including the current version number, so that users can easily get information about your plugin with Kirby's plugin methods.
Add a README
In your README, describe the plugin in every little detail and how to use it:
- What is the purpose of the plugin and who profits from using it?
- How can the plugin be installed?
- How can users use the plugin? Ideally, add step by step instructions, not just a few examples. This is particularly important if using the plugin requires some background knowledge or user code.
- Are there any config settings? If so, what is each config setting good for?
The easier you make it for users to use your plugin, the more likely they will actually use it, star it and maybe even buy you a beer or two.
Add a license
Don't forget to add the license under which your plugin is published and if it is free or commercial.
If it is free but you want people to donate, add a link to the platform where you want them to donate or offer some options.
Promote your plugin
- Create an new topic in the Kirby 3 plugins category on the forum, ping @texnixe to make sure she'll mention it in the next Kosmos issue.
- Submit it to the Kirby plugins directory, currently either by making a PR to the getkirby.com repo or by creating an issue, but we will add a submit form in the future.
- Tweet it mentioning @getkirby.