Releasing changes to production

We aim to release changes to the live site once a sprint, with rare ad hoc releases as necessary. This generally follows a pretty simple process.

Regular releases

For our regular releases, we follow this process:

1. Before starting the release process, make sure any PRs that should be part of the release are merged into dev.

2. Under the ‘dev’ branch, change the version number in _config.yml. Refer to the current version and the Semantic Versioning Site to determine which version number to use. Here are some examples from our site that relate to the semantic versioning:

   • A bug with icon presentation in IE 11 would be a patch.
   • A routine data update would be a minor version.
   • Re-branding the website from USEITI to NRRD was a major version.

3. Open a PR from dev to master(usually done by the product manager or someone acting in that role).

4. Fill in the PR description with a list of major changes in that release as well as a preview link.

5. Draft a new release, drawing heavily from your list of changes/issues in your release PR.

   • Fill in the box for tag version with a “v” and your release number (no spaces).
   • Select master for the target branch. This is the branch where the release will be published.
   • Fill in the version number (with a “v”) and the date for the release title.
   • Save the release as a draft.

6. Use the Federalist preview link for the dev branch to carefully review the site and make sure only the expected things have changed.

   • It can be helpful to have the live site open in another window for visual regression testing.
   • Check different layouts and interactions, including the homepage, explore data pages, and a range of other templates.
   • Make sure data is still present and unchanged (or changed only in expected ways).

7. Based on their knowledge and skill sets, assign at least two other team members to review the PR.

8. The assigned team members should review changes, commits, and the preview to make sure everything looks as expected.

9. Once the assigned team members have reviewed and approved the PR, the product manager – or the team member acting in that capacity – will review and merge the PRs to the live site.

10. Publish your draft GitHub release that you set up in step 5.

11. Make sure Federalist successfully built the site and verify that the changes are live as expected (can take 5-10 minutes).

Celebrate!

Ad Hoc or Emergency Releases

Occasionally, we may have a situation, such as an urgent bug fix or data update, that necessitates an ad hoc release. If we have an urgent PR that needs to be released directly into production without going through the process of reviewing and merging all commits in dev, the product manager or a person acting in that capacity can decide to do an ad hoc release. In this case, we will follow the procedures for a release, with these key changes:

1. Change the version number in _config.yml and select your current branch for this change.
2. Set the PR up to go from your current branch directly into master.
3. Use the Federalist preview link for your branch to carefully review the site and make sure only the expected things have changed.
4. Assign at least two other team members to review the PR:
   • Code-related changes must have the developer and/or content strategist review them.
   • Content-related changes must have the content strategist, product manager, or program analysts review them.
   • PRs related to new designs must have the user experience designer review them (although these PRs probably will not be urgent and should just go through the normal release process).
   • Visual design-related PRs must have the content strategist or user experience designer review them.

Appendix: things to check while reviewing changes

For all of the things below, compare against the live site, looking for NEW issues or bugs introduced with the in-review PR. If you notice additional bugs that are shared between the live site and new PR, those don't need to be resolved before merging — open a new GitHub issue to describe the issue, and prioritize it for future sprints.

• Check that spacing and line breaks haven't changed (this is an easy way to spot unexpected CSS ramifications).
• Check that maps are appearing, shaded the same, and have hover behavior.
• Check several types of location profile pages to ensure data and liquid templates are working as expected. This often includes:
  • An offshore area
  • An opt-in state (AK, WY, MT, CO)
  • Non-opt-in state with lots of extractives (e.g. TX, ND, CA, UT, AZ)
  • State with some but minimal extractives (anything where extractives account for <1% of GDP)
  • State with no data in areas (ME, MA, DC)
• Check bar graphs: is there data? is the data the same? is hover behavior working?
• Check county/offshore area maps: does hover behavior work? do detail tables open?
• Open and close glossary links in a few places and test glossary search.
• Use links, maps, and dropdowns to navigate between pages and validate they all still work.
• View both tabs of the megachart on state profile pages.
• Review some content or custom layout pages:
  • About
  • How it works
  • Diving graphics
  • Case studies overview
  • Individual case study
  • Downloads
• Outlier layouts
  • Federal revenue by company
  • Reconciliation
• Search