A Checklist for the Craft Plugin Store
Like many of my posts here, this is another note to myself to help me when I have questions about getting things done.
I recently finished Pic Puller for Craft 3, available in finer Craft 3 plugin stores everywhere. But the point of this post is how it actually got there.
The conversion of the plugin from its Craft 2‑compatible version to Craft 3 was the first step of the process. Andrew Welch’s Pluginfactory.io really helped there.
The process of getting the plugin into the Plugin Store, integrated into the Craft 3 control panel, presented a different set things to figure out. With the assistance from Andrew Welch (as always, thank you, my friend) I got that figured out. I had stumbles along the way which resulted in the following checklist to make future me seem a little more adept at the process. I hope it helps you too.
First: since there is a Plugin Store FAQ it might be good to check to see if any of what I say below is still relevant because things change fast on this here Internet.
Second: there is a official “Pluging to the Plugin Store” post from the mothership. Read it here.
The Getting Into The Store Checklist
Here’s what you gotta do.
- Make a plugin.
- Have one branch that is named the major version of your plugin, “v1” or “v2” or whatever. Make the new version the default branch. You’ll also probably want a “develop” branch.
- Finish and test your plugin.
- Write some documentation. I put mine in a documentation.md file. You’ll need this later.
- Add a license to your plugin. It’s got to be the MIT license or the Craft license to be eligible for inclusion in the store. The license you choose will be included in the files of your plugin. I’m not your lawyer, but if you want to sell you plugin, pick the Craft license.
- I use Tower as my git client. However you git, create a new local tag for the release of your plugin. Or, better yet, use GitFlow and start a release of your plugin which will help take care of making your tag. Try using a number like 1.0.0 for the tag and then “Version 1.0.0” for the description.
- Post your plugin to a public Github repo.
- Back in Github, make a release using your tag. You’ll need to add some change log info in this step. I keep a changelog.md file in my plugin. If you do too, make sure these match up so people aren’t confused by conflicting documentation.
- Do you have a Packagist account yet? Make one if not.
- Add your plugin to Packagist, like I did here for Pic Puller.
- Create a Craft ID. This is how you tell Craft that you’ve got something that can be included in the store.
- Link up your Craft ID account with your Github account.
- Do you have documentation URL? You can link to your documentation.md file.
- Do you have a change log URL? You can link to your changelog.md file.
- If you’ve gotten this far, you can now add your plugin to your Craft ID account.
- If you’re going to charge for your plugin, you need to pick a price and a renewal price. Check the official page on pricing suggestions.
- Now that your plugin is in your Craft ID account, don’t hit submit yet, be sure you can install your plugin via composer first. Try it from your command line. Did it work? If so, submit for approval.
- Wait for approval. Pace. Check email. Celebrate.
Congrats! You’ve got a plugin in the store. You rock.
Now, how are you going to update that thing? Let’s assume there was something that needed updating. Let’s go over the process of making the update and getting that updated version showing up in the plugin store.
The Update a Plugin Checklist
- Update your plug in and make sure it works. This should be done in the “develop” branch. This is important later on.
- Do you need to change your scheme version? You will if you made a database migration. This schema change will trigger the migration to run for new users.
- Update the composer.json file in the root directory of your plugin with the new version number. If you didn’t change the schema, your local dev environment might not show the new version number. You can
composer updateto make Craft check the composer.json for your plugin though to check to be sure it’s working.
- Update your CHANGELOG.md at the root of your project to document the changes you’ve made for this new version.
- Make a note of what you put in the Changelog.md because you’ll use it next to create a tag for release.
- Add and commit your changes to the code.
- Choose “Start New Release Branch” in your Git Flow dropdown in Tower.
- Release name is something like “3.0.6” in the “develop” branch where you’ve been working.
- You’ll see a new “folder” icon under your branches in Tower with the name “release” and the release name within it.
- Now choose “Finish Release” from the Git-Flow dropdown.
- For the Tag Message to follow my pattern, I would then put “Version 3.0.6”, so my “Releases” link on Github looks nice and consistent.
- Now ‘push’ the develop and master branches to Github.
- Go to Github in your browser and find the releases tab for the repo, like here https://github.com/jmx2inc/picpuller-for-craft3/releases
- You should see the tag you just pushed on the page, but the last release is still your old release. Click the “Draft new release” button.
- Choose the tag you just made on the next screen.
- Release Title will be something like “Version 3.0.6”
- For the description, I’ll do something like this “## Fixed — The /services/AppManagement.php wasn’t using the table prefix and has been updated to fix this bug.”
- Then click “Publish release”
- If you’ve got automatic updates set up in Packagist, you plugin should have updated automatcially. Just in case, check out the plugin homepage on Packagist. For example, here’s the Pic Puller one. https://packagist.org/packages/jmx2/pic-puller
- While logged in you may see a message if automatic updates are not working. If that is the case, you may need to click the “Update” button to force an update so Packagist sees your new version. If you can’t be bothered with this button clicking, just set up the automatic updates. It’s like magic.
You’ve now published a release of your plugin.
Now it’s time for cocktail.