A blog probably of interest only to nerds by John Morton.

15Mar2018

A Check­list for the Craft Plu­g­in Store

Like many of my posts here, this is anoth­er note to myself to help me when I have ques­tions about get­ting things done. 

I recent­ly fin­ished Pic Puller for Craft 3, avail­able in fin­er Craft 3 plu­g­in stores every­where. But the point of this post is how it actu­al­ly got there. 

The con­ver­sion of the plu­g­in from its Craft 2-com­pat­i­ble ver­sion to Craft 3 was the first step of the process. Andrew Welch’s Plug​in​fac​to​ry​.io real­ly helped there. 

The process of get­ting the plu­g­in into the Plu­g­in Store, inte­grat­ed into the Craft 3 con­trol pan­el, pre­sent­ed a dif­fer­ent set things to fig­ure out. With the assis­tance from Andrew Welch (as always, thank you, my friend) I got that fig­ured out. I had stum­bles along the way which result­ed in the fol­low­ing check­list to make future me seem a lit­tle more adept at the process. I hope it helps you too. 

First: since there is a Plu­g­in Store FAQ it might be good to check to see if any of what I say below is still rel­e­vant because things change fast on this here Internet.

Sec­ond: there is a offi­cial Plug­ing to the Plu­g­in Store” post from the moth­er­ship. Read it here.

The Get­ting Into The Store Checklist

Here’s what you got­ta do.

  1. Make a plugin. 
  2. Have one branch that is named the major ver­sion of your plu­g­in, v1” or v2” or what­ev­er. Make the new ver­sion the default branch. You’ll also prob­a­bly want a devel­op” branch.
  3. Fin­ish and test your plugin.
  4. Write some doc­u­men­ta­tion. I put mine in a doc​u​men​ta​tion​.md file. You’ll need this later.
  5. Add a license to your plu­g­in. It’s got to be the MIT license or the Craft license to be eli­gi­ble for inclu­sion in the store. The license you choose will be includ­ed in the files of your plu­g­in. I’m not your lawyer, but if you want to sell you plu­g­in, pick the Craft license.
  6. I use Tow­er as my git client. How­ev­er you git, cre­ate a new local tag for the release of your plu­g­in. Or, bet­ter yet, use Git­Flow and start a release of your plu­g­in which will help take care of mak­ing your tag. Try using a num­ber like 1.0.0 for the tag and then Ver­sion 1.0.0” for the description.
  7. Post your plu­g­in to a pub­lic Github repo.
  8. Back in Github, make a release using your tag. You’ll need to add some change log info in this step. I keep a changel​og​.md file in my plu­g­in. If you do too, make sure these match up so peo­ple aren’t con­fused by con­flict­ing documentation. 
  9. Do you have a Pack­ag­ist account yet? Make one if not.
  10. Add your plu­g­in to Pack­ag­ist, like I did here for Pic Puller.
  11. Cre­ate a Craft ID. This is how you tell Craft that you’ve got some­thing that can be includ­ed in the store.
  12. Link up your Craft ID account with your Github account.
  13. Do you have doc­u­men­ta­tion URL? You can link to your doc​u​men​ta​tion​.md file.
  14. Do you have a change log URL? You can link to your changel​og​.md file.
  15. If you’ve got­ten this far, you can now add your plu­g­in to your Craft ID account.
  16. If you’re going to charge for your plu­g­in, you need to pick a price and a renew­al price. Check the offi­cial page on pric­ing suggestions.
  17. Now that your plu­g­in is in your Craft ID account, don’t hit sub­mit yet, be sure you can install your plu­g­in via com­pos­er first. Try it from your com­mand line. Did it work? If so, sub­mit for approval.
  18. Wait for approval. Pace. Check email. Celebrate.

Con­grats! You’ve got a plu­g­in in the store. You rock.

Now, how are you going to update that thing? Let’s assume there was some­thing that need­ed updat­ing. Let’s go over the process of mak­ing the update and get­ting that updat­ed ver­sion show­ing up in the plu­g­in store. 

The Update a Plu­g­in Checklist

  1. Update your plug in and make sure it works. This should be done in the devel­op” branch. This is impor­tant lat­er on.
  2. Do you need to change your scheme ver­sion? You will if you made a data­base migra­tion. This schema change will trig­ger the migra­tion to run for new users.
  3. Update the composer.json file in the root direc­to­ry of your plu­g­in with the new ver­sion num­ber. If you didn’t change the schema, your local dev envi­ron­ment might not show the new ver­sion num­ber. You can composer update to make Craft check the composer.json for your plu­g­in though to check to be sure it’s working.
  4. Update your CHANGEL​OG​.md at the root of your project to doc­u­ment the changes you’ve made for this new version.
  5. Make a note of what you put in the Changel​og​.md because you’ll use it next to cre­ate a tag for release.
  6. Add and com­mit your changes to the code.
  7. Choose Start New Release Branch” in your Git Flow drop­down in Tower.
  8. Release name is some­thing like 3.0.6” in the devel­op” branch where you’ve been working.
  9. You’ll see a new fold­er” icon under your branch­es in Tow­er with the name release” and the release name with­in it.
  10. Now choose Fin­ish Release” from the Git-Flow dropdown.
  11. For the Tag Mes­sage to fol­low my pat­tern, I would then put Ver­sion 3.0.6”, so my Releas­es” link on Github looks nice and consistent.
  12. Now push’ the devel­op and mas­ter branch­es to Github.
  13. Go to Github in your brows­er and find the releas­es tab for the repo, like here https://​github​.com/​j​m​x​2​i​n​c​/​p​i​c​p​u​l​l​e​r​-​f​o​r​-​c​r​a​f​t​3​/​r​e​l​eases
  14. 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.
  15. Choose the tag you just made on the next screen.
  16. Release Title will be some­thing like Ver­sion 3.0.6
  17. For the descrip­tion, I’ll do some­thing like this “## Fixed — The /services/AppManagement.php wasn’t using the table pre­fix and has been updat­ed to fix this bug.”
  18. Then click Pub­lish release”
  19. If you’ve got auto­mat­ic updates set up in Pack­ag­ist, you plu­g­in should have updat­ed automat­cial­ly. Just in case, check out the plu­g­in home­page on Pack­ag­ist. For exam­ple, here’s the Pic Puller one. https://​pack​ag​ist​.org/​p​a​c​k​a​g​e​s​/​j​m​x​2​/​p​i​c​-​p​uller
  20. While logged in you may see a mes­sage if auto­mat­ic updates are not work­ing. If that is the case, you may need to click the Update” but­ton to force an update so Pack­ag­ist sees your new ver­sion. If you can’t be both­ered with this but­ton click­ing, just set up the auto­mat­ic updates. It’s like magic.

You’ve now pub­lished a release of your plugin. 

Now it’s time for cocktail.