New IPT Version Launch Procedure

Introduction

A checklist documenting the ordered steps of the release and launch procedure of the IPT. Learn as you go – review and adjust the process to streamline it.

Many players are involved in the process, not least the GBIF Communications team and GBIF Systems Administrator. Make sure they are on standby ready to help before embarking on the launch.

Pre-release steps

  1. Label all issues related to version

    • Label issues with issue type (Bug, Enhancement, Duplicate, Won’t fix, etc.), used in statistical reporting.

    • Label issues requiring a change in the user manual with UserManual.

    • Assign milestone to each issue, used to group all issues addressed since last version was released. For example, here are all issues addressed in version 2.3.5.

  2. Finalize work

    • Work on each issue should be considered "Done". The meaning of "Done" being understood and agreed on by the entire team, but ideally this also includes having written automated testing, performed code reviews as well as UI testing.

  3. Finalize translations

    • Work translating each language (by volunteer translators in Crowdin) should be both 100% translated and approved.

    • The translation pull request from Crowdin should be merged.

    • Open the UAT IPT to volunteer translators to verify their work in vivo (see step below).

  4. Test release candidate

    • Update the UAT IPT with the release candidate. There is a helper script in /etc/ipt/upgrade.

    • When it makes sense, invite volunteer testers to join efforts by sending an invitation to the IPT mailing list explaining how to request an account on the UAT IPT and what areas of testing to focus on.

    • Test new features — issues labelled as Enhancement. Directly involve the reporter of the enhancement in testing, to verify its implementation meets their expectations.

    • Test bug fixes — issues labelled as Bug. Try to reproduce the bug following the detailed instructions provided in the issue description.

    • Test all areas possibly affected by code changes. Build a list of affected areas to test by scanning the commit history.

    • Always ensure that GBIF can index the data published by the IPT, for example using the GBIF Data Validator.

    • Put on different user hats, testing as an "Admin", "Manager" and "Manager with registration rights".

    • Where applicable, test the IPT in both production and test mode.

    • Where applicable, perform cross-browser testing.

  5. Update the User Manual.

    • Add/update user manual content – see issues labelled as UserManual.

    • After applying all changes in English, send a message using Crowdin to request translators translate the user manual, though note this does not block the software release.

  6. Update Release Notes

    • The Release Notes should contain all the information needed to properly upgrade their IPT to the latest version. Typically it contains the following sections:

      • Upgrade instructions

      • Post-upgrade instructions

      • Important changes in this release

      • When all else fails

Release and public launch steps

  1. Release the new version using Jenkins

    • Check the WAR, RPM and Docker image have been released!

    • Create a release on GitHub (using the same tag), so people watching the repository are notified.

  2. Update GBIF IPTs to new version

    • Update production instances. There is a helper script in /mnt/auto/ipt-data/upgrade:

      • BID IPT — customized (see below for help).

      • EU BON IPT — customized (see below for help).

      • GRIIS IPT — customized (see below for help).

      • Regional IPTs — vanilla IPTs on cloud.gbif.org.

      • GIASIP IPT — vanilla. Note this runs in test mode but is treated like it’s in production.

    • Update Test/Sandbox instances:

      • Demo IPT — vanilla. Note It is always a good idea to cleanup old resources to save disk space.

      • UAT IPT — vanilla.

      • Development IPT — vanilla.

      • Training IPT A, B and C — customized. This update can be delayed if required by the Participation team.

      • Test EU BON IPT — vanilla. Seems no longer to be used.

    • Simple customizations for the above IPTs are done by

      1. changing the logo image in menu.ftl#L12,

      2. removing the test image in menu.ftl#L20 (where applicable) and

      3. tweaking the CSS in main.css#L297.

      before an upgrade, the custom logo image(s) and CSS need to be backed-up/preserved and then copied back to the expanded data directory.

  3. For a major or minor release (but not a patch release), add a new version to the user manual

  4. Publish blog post

    • Publicize in some detail, select improvements that users will value. For example, here is an example blog post for IPT v2.2.

    • Be sure to acknowledge volunteer translators and coders that contributed to the release.

    • Review the blog post with the help of the GBIF Communications team before publishing.

  5. Update release history.

    • Add section for new version including a link to the .war download, release notes, user manual, how many issues were addressed broken down by type, blog post and a short summary of what changed.

    • Add/update a plan for the next release, or use the generic statement.

  6. Announce to IPT mailing list

    • Keep the message short so that people actually read it, linking to the blog post when applicable that has more detailed information about the release. Here are a couple example announcements for 2.2 major release, 2.3.3 minor release and 2.3.4 security patch release

    • Highlight GBIF’s vigilance in keeping the IPT secure, while reminding people of the importance of updating their instance with this latest version.

  7. Broadcast on social media

  8. Reward volunteers

    • Say thank you again, in addition to saying it in the blog post and mailing list announcement.

    • Encourage volunteers to include this experience on their CV.