Merge pull request #866 from torchbox/upgrade/wagtail-2.16

Support-377: Wagtail 2.16 upgrade

docs/support-runbook.md

@@ -0,0 +1,50 @@
+# Support runbook
+
+This document describes possible ways in which the system may fail or malfunction, with instructions how to handle and recover from these scenarios.
+
+This runbook is supplementary to the [general 24/7 support runbook](https://intranet.torchbox.com/propositions/design-and-build-proposition/delivering-projects/dedicated-support-team/247-support-out-of-hours-runbook/), with details about project-specific actions which may be necessary for troubleshooting and restoring service.
+
+See also our [incident process](https://intranet.torchbox.com/propositions/design-and-build-proposition/delivering-projects/application-support/incident-process/) if you're not already following this.
+
+**Note: Remove the above intranet references if this project will be supported by the client's team, or handed to a third party for support. Consider whether to incorporate any scenarios from the general runbook in these cases.**
+
+## Support resources
+
+- Git repositories:
+  - [Project repository]()
+  - Include repositories for other dependencies relevant to the runbook
+- [Scout APM]()
+- Papertrail logs:
+  - [Production]()
+  - [Staging]()
+- [Sentry project]()
+- S3 buckets:
+  - `project-production`
+  - `buckup-project-staging`
+- ... Any other resources useful for troubleshooting the site ...
+
+## Scenario X: [Description of overall scenario, e.g. 'Data rejected by AnnoyingService API']
+
+### 1. [Put the most important/likely thing to check first, e.g. 'Is authentication failing?']
+
+- Description of what to check (e.g. 'Does the error response mention "invalid credentials"?')
+- Could involve multiple steps (e.g. 'Manually test the credentials with this example cURL command: ...')
+
+**Action if there is an issue with [thing]**
+
+- Description of what to do (e.g. 'Reset the credentials and update the environment variables X and Y with the new details')
+- Include technical steps (if fixable), who to raise the issue with (if externally-managed), any specific instructions for communicating with the client
+
+### 2. [Next thing to check if first check wasn't the problem, e.g. 'Is the site posting malformed data?']
+
+...
+
+### 3. [Include as many checks as necessary to cover the possible explanations for the scenario]
+
+...
+
+## Scenario Y: [Another, separate scenario, e.g. 'Search not returning any highlighted results']
+
+...
+
+## Scenario Z: [Include as many different scenarios as necessary for known failure modes of the site]

docs/upgrading.md

@@ -0,0 +1,26 @@
+# Upgrading guidelines
+
+This document describes aspects of the system which should be given particular attention when upgrading Wagtail or its dependencies.
+
+## Critical paths
+
+The following areas of functionality are critical paths for the site which don't have full automated tests and should be checked manually.
+
+(If this information is managed in a separate document, a link here will suffice.)
+
+### 1. [Summary of critical path, e.g. 'Donations']
+
+[Description of the overall functionality covered]
+
+- Step-by-step instructions for what to test and what the expected behaviour is
+- Include details for edge cases as well as the general case
+- Break this into separate subsections if there's a lot to cover
+- Don't include anything which is already covered by automated testing, unless it's a prerequisite for a manual test
+
+## Other considerations
+
+As well as testing the critical paths, these areas of functionality should be checked:
+
+- For unknown reasons, [the sidebar is not working properly](https://github.com/wagtail/wagtail.org/pull/144)
+  after upgrading from Wagtail v2.15 to v2.16 . We decided to disable the sidebar. When the legacy sidebar removed in
+  Wagtail 2.18, then that is the time to fix this issue If the problem still persists.

mkdocs.yml

@@ -18,3 +18,5 @@ nav:
       - 'Rebuild Approach': 'implementation-specs/finalised-rebuild-approach.md'
       - 'Programme Page': 'implementation-specs/programme-page.md'
       - 'Content relationship via API': 'implementation-specs/content-relationships.md'
+      - 'Support runbook': 'support-runbook.md'
+      - 'Upgrading guidelines': 'upgrading.md'