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 Rabbit with 1000 Repos 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.
- You’ll need a Keybase account. Depending on what Zoom does with Keybase, this info may become out of date.
- Install Vagrant and
- 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.
- Export this unupdated app to a
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.
- 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.
- Get the updated app running correctly, and export it
to a different
- Create a fake Sandstorm project that doesn’t have an app
associated with it using
vagrant-spk initin an empty folder. Install the unupdated app via direct upload of the
.pkgfile 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 devfor this part. Starting the VM gives you a sandboxed Sandstorm to mess with without doing anything else.
- Upload the updated app
.pkgand upgrade your test grains in this VM. Make sure a grain upgrade works correctly.
- 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-devmailing list and state your intent to take over maintenance.
- You’ll eventually be given a keyfile to
catonto 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
catjust in case!
- 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.
- 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
- Wherever you’re hosting the repo, ensure you can get feedback from users, and, more importantly, code from contributors.
- 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!
- If you ever decide to give up maintenance, let
sandstorm-devknow, put a notice on the
READMEfor 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!