Storytelling Tool update process

Owned by Gregor Moss
Last updated: Nov 17, 2020
2 min read

This is the process that should be followed (along with satisfying the Laser Eye Checklist) when pushing updates to the Storytelling Tool. The purpose is to ensure minimal disruption to the version(s) in use by the general public or any particular groups. A similar process is laid out in the Contribution Guidelines of the repository, but this provides a bit more detail on some of the points.

  1. Open an issue on the project's Jira list to summarize/capture the work about to be done
  2. Make a fork of the repository
  3. Make all code changes on that fork
  4. Test the work on the developer's local machine and in as many different browsers as is practical
    1. Run "npm test" from the command line and make sure both the Browser and Node tests are passing
    2. Run a static HTTP server in order to run the manual tests (see Readme for up-to-date list)
  5. Create database migration scripts, making sure to update the data version to match the new release
  6. Set the version number in package.json as appropriate. It is recommended to follow the Semantic Versioning rules.
  7. Open a Pull Request against the main branch of the upstream fork
  8. Review the work and make updates as required (at least one other person must review)
  9. Merge the Pull Request into the main branch of the upstream fork (the reviewer will usually do this)
  10. Test the Staging site (https://staging-stories.floeproject.org) once it has finished rebuilding
    1. check the GitHub Actions page to track build progress 
    2. Run through the Storytelling Tool Minimal Testing Grid
    3. If any issues are encountered, document them as appropriate (new Jira, amend original Jira, etc.)
  11. Back up the production site's database and uploaded files as necessary
  12. Create a Pull Request or merge the main branch into the production branches (link below)
    1. CI/CD should automatically run any data migration scripts
  13. Test the production sites
    1. Examine all the stories to make sure they continue to look correct
    2. Create test stories on those sites where editing is enabled
    3. Remove any test stories that were created in the step above

Note: there are different versions of the tool running from different deployment branches. For details on which branches are deployed to which URLs, please see the Branches Documentation.