Heads up, we’re moving to our new wiki today.
tl;dr: the wiki looks different but mostly works like a wiki and you can ignore this unless it affects you personally.
THIS IS A WORK IN PROGRESS and if something feels wrong, it’s either a bug to be fixed or something we’d like to hear about so we can improve.
I’m just going to explain why this is happening, as change is always scary.
These were the problems we were trying to solve:
- MoinMoin is kinda old and crusty.
- Everything else moved to GitHub, which offers a wiki, so if we were dumping other old and crusty services for GitHub equivalents, moving the wiki made sense, too.
But almost immediately, we discovered we had a new problem:
- GitHub’s built-in wiki sucks, too.
So we stopped for a bit to think about what we’d like the perfect wiki to do, and here’s some things we came up with:
- We liked the idea of the wiki being backed by a git repo, so wiki users can use a web interface, but there’s nothing stopping us from iterating on the content with a perl script locally, too.
- We have a separate Git repo for the wiki contents (“sdlwiki”) so we don’t get a ton of update spam in the main SDL repo, since wiki commits tend to be smaller and more frequent than source code commits (there was 7000+ commits in the MoinMoin data set).
- We publish the contents of this repo at wiki.libsdl.org with some other bits of user interface.
- As changes are pushed to this repo, we get a notification from a GitHub webhook, like we do to tweet and post to Discourse. This notification causes wiki.libsdl.org to pull the latest and generate static HTML for changed files.
- Each page has an “edit” button as one would expect from a Wiki. Clicking the edit button pushes the user through GitHub OAuth, which will tell wiki.libsdl.org their valid GitHub login name (and let them optionally create a GitHub account, etc). This fixes a massive problem we had with MoinMoin: spammers. They have to have a valid GitHub account, pushing spam detection onto GitHub, and causing a barrier to entry for spammers.
- Submitting an edit causes wiki.libsdl.org to make a topic branch in a local clone of the sdlwiki repo, listed as authored by that GitHub user, with the changed file as the only commit. It then pushes this to GitHub and generates a Pull Request for it with the GitHub API. User is redirected to this pull request. They’re listed as the author on the commit in the PR, but the actual PR will come from a bot ("@SDLWikiBot").
- We humans go through pull requests and approve/merge them like any other. When merged, wiki.libsdl.org starts publishing the changes immediately at this point because it got a webhook notification.
- Extra credit: if we like the user, we mark them as trusted, and their edits stop making pull requests and just push the changes right to the main sdlwiki repo, reducing friction.
- GitHub manages accounts, deals with spammers, etc.
- We can pipe this stuff through pull requests, keep a revision history, etc.
- Contributors don’t have to fork the repo or worry about keeping it up to date. They just edit in a webpage, replacing the latest contents.
- If someone wants to make a pull request by cloning the repo (they want to run a perl script over a bunch of files, etc), they can still do that in the usual GitHub ways.
- If two people edit the same page, they’re in separate pull requests and GitHub will tell us we need to fix it up if it can’t automatically merge, but that’s something we can handle on our end.
- If someone is obnoxious or a spammer, we can block them on the wiki and then they can’t submit further pull requests (but they will still have access to read the wiki).
- We can offer zip files of offline HTML, since we control the software.
- Editors can interchangeably choose MediaWiki or GitHub-flavored Markdown for any given page.
So I took a few weeks to write this, and that lives at the ghwikipp project page.
One more benefit: Edits to the SDL headers and the wiki are now bridged, so changes to one will show up in the other place automatically. That code is sitting in SDL/build-scripts/wikiheaders.pl, and runs in a cronjob on libsdl.org.
This is now live on https://wiki.libsdl.org/ … This is still early times, so some MoinMoin content hasn’t been cleaned out, and there are lots of CSS tweaks and little changes we would like to make still.
But we are happy with this as a first cut and intend to continue to improve it, and appreciate your feedback and questions here.