NetLogo Web Release Process

The goal of the NetLogo Web release process is to give a single source of truth for end-user information on release updates, namely the What's New page on netlogoweb.org. We'll also include our version updates for reference on that page. It's also desirable to have the standard practices recorded for reference.

Process for Version Update

Even though Tortoise and Galapagos are primarily only used by the CCL for our projects, having version numbers helps when discussing updates to the software both internally and with external users.

• We will try to follow something resembling a proper semantic versioning scheme - MAJOR.MINOR.PATCH.
  • PATCH is for bug fixes and non-disruptive internal infrastructure changes only.
  • MINOR is incremented for added features but no API changes.
  • MAJOR is for API changes.
• Galapagos doesn't really define its own public API; it would be odd for another piece of software to depend on it directly. As such, we will lock the MAJOR version of Galapagos to the Tortoise MAJOR version.
• It is possible to add features to Galapagos without adding to Tortoise, so the the MINOR version of Galapagos will always outpace Tortoise's MINOR version.
• And the PATCH version will probably change regularly for both.

Workflow

• Add any commits to the Galapagos main branch as they are completed. All tests should pass.
  • It is permissible to force-push fixes to main to fix omissions or small bugs in order to preserve a linear commit history, but hopefully this will be a rare occurrence.
  • Verify that the changes don't have any undesirable side-effects and perform any other smoke testing needed at https://staging.netlogoweb.org.
• Release main to production on a schedule, hopefully every two weeks, marking the release with a matching tag in Github.

Process for Release

• Update the models library in Tortoise and Galapagos if there are any changes to bring in.
• Decide on release versions for Tortoise and Galapagos.
• If there are Tortoise changes for the release not yet published and used in Galapagos, publish them from Tortoise and update the version in Galapagos' build.sbt.
• Update the NETLOGO_VERSION in session-lite.coffee.
• Update the release notes.
  • Grab anything relevant from the Galapagos commits, along with the Tortoise and NetLogo commits if there are updates to those upstream packages.
  • Bug fixes and features should be included in release notes. Strictly internal issues such as refactoring, dependency updates without new features, and similar can be omitted.
  • Add the version number along with the date for the release, also.
• Do a quick check of the release notes and version locally.
• Merge and push to main and run some smoke tests in staging once deployed.
• Merge and push to production and run smoke tests in production once deployed.
• Mark the release commit with a proper release tag.
• Tortoise: If the release included a published Tortoise update, also mark the appropriate commit in Tortoise's main branch with a release tag.

Smoke Testing

Here is a short list of things to smoke test when performing a release to staging or to production. This list isn't exhaustive, but it should give a good idea that nothing major is broken. If releases affect or don't affect particular functionality then more or less testing should be done.

• Navigation (between models) - On the launch page, confirm you can search for other models, that you can select a different model and have it load, and that you can click "back" in the browser to go to the previous model.
• Model simulation - A good model to check is Wolf Sheep Predation.
  • Run a model, make sure the basics work.
  • Check that plots are working.
  • Check that authoring works - try moving a widget and editing its properties.
  • Enter a command or two in the Command Center.
  • Edit some code in the NetLogo Code tab, recompile, and confirm the model still runs.
  • Run exports to an nlogo file and an html file.
• NetTango Builder
  • Load the WSP testing defaults
  • Play with some blocks, confirm they generate code
  • Recompile the NetLogo model to confirm block code are coming in.
  • Test an export of the model HTML, open it to confirm it worked.
• Documentation - Check the What's New page, check one or two of the Documentation pages.

Emergencies

If an update has to go out immediately, for an urgent bug fix or a feature, it should bypass the main branch and be pushed immediately to production, once properly tested on its own. Release tags should then be added as normal for Galapagos and Tortoise, if appropriate. The main branch will have to rebase to the new production before the normal deploy cycle can continue.

Future Items

• Another great addition would be A/B feature testing. This allows new features to appear for some users for "live" tests, but they can also be easily deactivated by system configuration if things are not working right, or fully activated if things are going well.
• There is an opportunity to automate the creation of the What's New information.
  • Ideally we'd be able to pull the commit messages from Github since the prior releases (NetLogo, Tortoise, Galpagos) into a document as a starting point.
  • Currently the What's New page is plain HTML, it might be nice to have the updates delivered in an easy to edit format like Markdown that is auto-converted.