Define process for documenting recommended/previous changes

[vanitabarrett]

Background

Sometimes we make changes in feature and fix releases which don't require users to make changes in order to update (so it's not a breaking change), but they may need to make changes if they want to benefit from the change.

We've got 3 changes like that at the moment which we've made in GOV.UK Frontend but haven't told users about yet:

• https://github.com/alphagov/govuk-frontend/issues/1758
• https://github.com/alphagov/govuk-frontend/issues/2196
• https://github.com/alphagov/govuk-frontend/issues/1829

What

We should define and document a process for dealing with this kind of work, for v4.0.0 and in the future. Previously, we've made the assumption that these changes will be documented in the next breaking release. However, we know breaking releases are challenging for users already as the release notes tend to be very long and we're potentially asking them to make a lot of changes. Does it make sense for these changes to be included here, especially when the change itself isn't included in the release?

Some questions I think we have:

• Should these changes be documented in the release notes of the next breaking release?
• If we don't document these in breaking release notes, what are the alternative options? When will we tell people about the change they might need to make? Are there any other comms channels we can use?
• If we do document these in breaking release notes, how do we talk about them? Do we explain that the change hasn't been made in that release?

Who needs to know about this

Developers; Tech Writer; Content Designer

Done when

• [x] We have a process for dealing with the three cards above
• [x] If the three cards above are being included in v4.0.0, make sure they're attached to the milestone
• [x] If we're confident in the process, make sure it's documented somewhere
• [x] If it's something we're trialling for v4.0.0, make sure there's a follow-up card to revisit how it went

[vanitabarrett]

We were going to include the changes mentioned in the description of this PR in the 3.14.0 release notes. However, we've decided against doing this for the reasons mentioned here.

Having discussed this with the other developers on the team, we think a suitable process for issues like this that come up in the future (where we have recommended, but non-breaking, changes for people to make) would be:

1. Make the change in a feature/fix release
2. Document our 'recommended steps' in the release notes for that release. Make clear that this isn't a breaking change, but we recommend people make the change
3. In the next breaking release, refer to the changes/release notes again. More briefly this time, perhaps linking to the original release notes, but making it more strongly recommended that users make this change. At some point we need to make the assumption that people have made this change so we can stop supporting the users who haven't - this is probably that point.

I'm not sure if we want to document the above anywhere other than this Github issue?

However, for the changes listed in the PR description, the steps users need to take were not documented in the release notes when they were released. Following the above process, we'd still want to talk about them in the v4.0.0 release, so it probably makes sense to include them there. It will lengthen the v4.0.0 release notes a bit, but at least it gives us a clean slate for the next time this kind of issue crops up.

The only other alternative we came up with is adding them to the Changelog file separately from any release, but I’m not sure how we’d then share that around with users and motivate them to take action - I think we’d have to bring it up in v4.0.0 again.

[vanitabarrett]

Going to take this off the v4.0.0 milestone - we've made the decision for v4.0.0. We can do the write-up separately.

[EoinShaughnessy]

Closing this issue as we addressed it in #2523.