Resurrecting dokuwiki-sandstorm & How to Take Over Sandstorm App Packaging

I’m now maintaining the Sandstorm App Store version of DokuWiki, a nice, lightweight wiki webapp.

I use DokuWiki along with Wekan to organize my comic and animation projects. Both The Wizard and The Metalsmith and The Industrious Rabbit have a combo of DokuWiki for scripts, marketing details, links/reference material, and other long-form text content, and Wekan is my big ol’ kanban board for managing work.

Since the original DokiWiki was a few years out of date, and a lot has changed both in DokuWiki and the PHP world in general, the app’s going to be updated slowly to the latest revision, so those folks with plugins installed that may fail on newer DokuWikis have time to get that resolved before new versions come along. Check the GitHub Repo for more information on that process, and if you have PRs/questions/etc.

I want to take over a Sandstorm app! How do?

So you have a favorite app you want to start maintaining, and it might even be one of mine if I decide to stop maintaining Hugo or DokuWiki. How do you take it over? Well, here’s the process I went through with taking over Hugo and DokuWiki. This is current as of July 2020.

  1. You’ll need a Keybase account. Depending on what Zoom does with Keybase, this info may become out of date.
  2. Install Vagrant and vagrant-spk.
  3. Get the project running locally, in its current state and at the version matching what’s in the App Store. Depending on the quality of the project’s repository and the project itself, this may be very easy or very hard. This might also require a lot of internet searching, lots of machine provisioning and reprovisioning using Vagrant, learning how to log debug output to stdout and stderr from whatever services encompass the app, and poking around a running grain using vagrant-spk enter-grain. Unless something is truly broken, this is not the time to fix up minor annoyances.
  4. Export this unupdated app to a .pkg file via vagrant-spk pack. You’ll have to do the GPG and Keybase dance to be able to sign the package, so create a GPG key if you don’t already have one. Commit and push a new branch with this set of modifications so you can roll back to this state easily.
  5. Upgrade the app. Depending on the application, this may involve a small upgrade at first, or may involve going straight to the latest version. I went to the latest version with Hugo and added a note about breaking changes in the admin area of the app as well as on the app’s app store page. With DokuWiki, I planned a set of smaller upgrades, taking a few weeks to get up to the latest version, since DokuWiki is a much more complicated piece of software to upgrade than Hugo.
  6. Get the updated app running correctly, and export it to a different .pkg file via vagrant-spk pack.
  7. Create a fake Sandstorm project that doesn’t have an app associated with it using vagrant-spk init in an empty folder. Install the unupdated app via direct upload of the .pkg file into this fake project and make sure it works correctly, spawning whatever grains you need to for testing. You do not need to use vagrant-spk dev for this part. Starting the VM gives you a sandboxed Sandstorm to mess with without doing anything else.
  8. Upload the updated app .pkg and upgrade your test grains in this VM. Make sure a grain upgrade works correctly.
  9. If the original repo has a message about looking for a new maintainer, try asking there if they want to turn it over to you. Otherwise, head to the sandstorm-dev mailing list and state your intent to take over maintenance.
  10. You’ll eventually be given a keyfile to cat onto your Sandstorm keyring. Do just that: cat < provided-key >> ~/.sandstorm/sandstorm-keyring. Ensure the app ID for the original app shows up with vagrant-spk listkeys. Back up your keyring before doing the cat just in case!
  11. Publish your app to the app store and wait for feedback. Depending on the level of changes, it can be a while to get feedback and to get the updated app to the quality level it needs to be at.
  12. After your app has made it onto the store and you’ve successfully done a release or two, consider automating the upgrade process as much as you can, where you can, to reduce the friction of putting out new releases. I do this with hugo-sandstorm and dokuwiki-sandstorm.
  13. Wherever you’re hosting the repo, ensure you can get feedback from users, and, more importantly, code from contributors.
  14. Once you have a few releases out, and can maintain a release schedule, then worry about fixing minor annoyances or edge case bugs. Remember, you’re spending your free time on this, so choose wisely what you work on, and ask for help when possible!
  15. If you ever decide to give up maintenance, let sandstorm-dev know, put a notice on the README for the repository, and (optionally) make the repo read-only so that no new issues can be posted. If someone else wants to take it over, they can fork it and repeat this very process!