Updating Keystone.guru

In order to update Keystone.guru, you need to create a new Release. A release has an optional Changelog, but I do recommend filling it in. The created release is pushed out to Reddit (on /r/KeystoneGuru) and an announcement is created in the Keystone.guru Discord. Unless you tick the silent button if you don't want to bother people with an insignificant minor change you did.

Using releases is very important for the Javascript code since it is versioned by release. In the past I had issues with creating an app.js which would be happily cached by browsers, and an update of the site would not trigger a cache refresh. As a result, people encountered all kinds of problems when returning to the site because they're using an old Javascript version. As a result, files called app-v5.0.1.js are now created upon every new release.

Creating a release

When logged in as an Admin, from the top right click the dropdown to expand the navigation menu. From there, click View releases. Then again in the top right is a Create release button.

Default Admin credentials are [email protected], password password (this ONLY works for the default values in your local environment, obviously I changed the password on any public-facing version of Keystone.guru)

Fill in the details as you see fit. I don't use semantic versioning for the site, though maybe I should switch to it. I roughly use the following scheme:

• Major version upgrade for big new features
• Minor version upgrade for smaller new features
• Bugfix version for bugfixes/minor tweaks or mapping updates

Don't forget to enter a v before the release. If you mess it up I will haunt you ;). When you eventually press Submit, please ctrl + click the button to open it up in a new page, just in case. If something errors out (such as the communication with Github) you don't want to have to start all over again writing your release. Ask me how I know.

When you press the Submit button, a few things happen. First, a new ticket is created in the Keystone.guru repository (such as v6.9.5). This automatically mentions tickets inside the release, and it will show on the tickets that you're releasing what release they're for. Pretty handy and well structured. This ticket can also be used to push any changes on that you require while testing your release. If you found a bug you can use that ticket number to commit your changes on.

Secondly, a pull request is created from development to master. This triggers a Github Action which will deploy your release on https://staging.keystone.guru/. This is a copy of the setup of the production environment and allows you to properly test your changes before you push them live. From then on, as long as the pull request exists, any push you do will re-deploy your code to the staging environment.

** WARNING ** don't push too quickly after one another until I resolved https://github.com/Wotuu/keystone.guru/issues/1866. Otherwise, multiple pipelines will run at the same time and it'll mess up the environments and require manual fixing. A bit shitty but I know about it now so I work around it, until I get sick of it and solve that ticket.

Creating a release file

This used to be an automatic thing, but file permission hell with Docker setup makes this a manual task instead. When you've created a release, a text area with JSON at the bottom appears. You need to take this json and create a new release file manually under database/seeders/releases/. You then need to commit and push this file under the new release ticket that was just created on Github.

Merging the pull request

When you're confident the changes you've done work, you can merge the pull request to master. This will trigger another Github action to deploy to the production site. For more information on the deployment process see https://github.com/Wotuu/keystone.guru/wiki/Deployment-procedure.

After this is done you'll get a nice Discord popup confirming your release. Then please do double check your work on the actual production site. Also don't ever release right before going to bed, you're risking breaking the site while nobody is around to fix it. Just don't do it. If you messed someone up the special Discord channels will start yelling at you immediately. Try not to stress out and fix the issue :-).