Decide and document how to release a patch fix for GOV.UK Frontend if there are unreleased changes on main

alphagov / govuk-frontend

GOV.UK Frontend contains the code you need to start building a user interface for government platforms and services.

https://frontend.design-system.service.gov.uk/

MIT License

1.16k stars 319 forks source link

Decide and document how to release a patch fix for GOV.UK Frontend if there are unreleased changes on main #1958

Closed hannalaakso closed 2 years ago

hannalaakso commented 3 years ago

What

In the run up to Frontend v4.0.0 (a breaking release) we should consider how we manage the source code in case we need to do a hotfix release when there are unreleased changes on the main branch that are not in a releasable state.

Why

If we needed to do a hotfix release prior to v4.0.0 we should know in advance the exact steps so that the process is quick and straightforward.

Who needs to know about this

Developers, Eoin

Done when

[x] We've reviewed the different options and their pros and cons
[x] We've met again and decided on an approach (see next steps)
[x] We've mobbed on setting up a test project to run through the steps for the two approaches
[x] We've drafted a document detailing how to publish a new version when there are unreleased changes on the main branch that are not in a releasable state
[x] We've tested the process in the draft document and made any necessary changes/tweaks
[x] Document has been reviewed by Eoin
[x] Document has been published
[x] We've set up branch protection for the new support branches we would need to create

hannalaakso commented 3 years ago

We should probably also consider how we manage backwards compatibility, for instance if after releasing 4.0.0 we need to release an urgent patch fixes 4.0.1 and 3.9.2.

hannalaakso commented 3 years ago

Following a review, we've documented what we want to test in https://docs.google.com/document/d/1avJPHEJ4hENt5LEcMwxp90zl1WS72Tx6qdoN2JOhXCE/edit#heading=h.5s859hln1k0l

hannalaakso commented 3 years ago

Following a conversation with Ollie and Vanita, the next steps are:

Turn ‘Problem 1’ into a draft doc and get it reviewed by devs/Eion. Decide how this doc will work with the existing Publishing docs
Investigate branch protection rules
Investigate ‘latest’ tag question on ‘Problem 3’?
Ask PM to help us define the scope of solving 3?

edit: I've moved these actions to the Done when list and split the Problem 3 into https://github.com/alphagov/govuk-frontend/issues/2004

hannalaakso commented 3 years ago

I've spoken to Eion about the draft doc. We've agreed that it would be good to avoid massive duplication between the 'Publishing' doc and this new one. I'm going to put together a very rough draft to see what the two publishing processes would like if compiled into one doc and Eion will then review it to see if it's viable to keep everything in that one doc. We should also bear in mind that there might yet be a third process (solution to Problem 3) added to that doc in the future too.

EoinShaughnessy commented 3 years ago

@hannalaakso Nice going on the draft doc! It was useful to see the two processes beside each other.

My vote would be for separate docs (if that complies with current Design System convention). As a user, I find it easier to consume information when each doc has one overarching objective. Also, if the two processes are in the one doc, that could make the doc rather long. (Maybe there's context I'm unaware of, though.)

Re duplication, it looked (to my untrained eye) like the processes are sufficiently different to publish separately.

What are your thoughts, @36degrees and @vanitabarrett ?

vanitabarrett commented 3 years ago

@hannalaakso @EoinShaughnessy I think having separate docs makes sense if they're sufficiently different. Do you think there is a point at which the two would/could converge? For example: if the steps for releasing a patch fix are different up until the point you actually check out the branch and run the npm commands to publish.

hannalaakso commented 3 years ago

@vanitabarrett @36degrees Here's the draft doc to review: https://docs.google.com/document/d/1Ybq_DonZqzX1vOrwxUmXC_ff9Yazdqn7ToEDVVay6ec/edit#

vanitabarrett commented 2 years ago

The devs talked about this at dev catchup today, as we might want to trial whatever process we decide on when we release the panel fix. This would be a good way to trial the process, but we also don't want to try it and tie ourselves into this way of doing releases before we've considered other options.

Actions:

[x] @lfdebrux to review the original 'support branch' process documentation and the doc which had our reasoning/thinking in with the problems we're trying to solve. Laurence wasn't on the team when this doc was created, so it would be good to get a new opinion
[ ] Developers to review https://gist.github.com/canton7/1570681 to see if these options would work for us (managing v4.0.0 in a feature branch instead of merging into main)

lfdebrux commented 2 years ago

@vanitabarrett thanks for sharing those docs with me. I've had a read through them and left a few comments but broadly they make sense to me.

Although I wasn't aware of the work already done when we were talking about this at the dev catch-up, I think my question still stands - I can't tell if we've made a firm decision on whether we're going to use a feature branch or not, which affects whether/when we want to use this process.

vanitabarrett commented 2 years ago

Thanks for taking a look @lfdebrux , glad it broadly makes sense! I'll take a look at your comments.

I think we'd prefer not to use a feature branch, mostly due to the maintenance overhead of keeping a feature branch going for a long period of time. But I'm not sure we've made a firm decision on it either. My opinion is that we want to merge into main rather than use a feature branch as long as this process to release fixes isn't too complex and works. We're pretty confident it does, but we've never actually tried it, and it may be that we hit a snag which means maintaining a long-running feature branch is less work. But unless we give this a go, we won't know for sure.

lfdebrux commented 2 years ago

@vanitabarrett I agree, testing this process definitely sounds like a good idea! If we're leaning towards not having a feature branch then I don't see any issues with doing it for the next release.

vanitabarrett commented 2 years ago

We've decided we're going to try and test this process for the 3.14.0 release. Going to move this ticket into 'blocked' for now until we've done the release. Once that's done, we can revisit the draft document and make any changes that came up when trialling the process.

vanitabarrett commented 2 years ago

We trialled this process when releasing 3.14.0 and it went really well - no hiccups! Where anything in the document needed clarifying or tweaking, I've added some suggestions (I think there was only one).

@EoinShaughnessy I think the next step for this is probably for you to take another look at the document to make sure you're happy with it. After that, we can raise a PR to publish it on Github.

I'm going to move this card into the Backlog now until you have time to pick it up

EoinShaughnessy commented 2 years ago

Hi @vanitabarrett, I've reviewed the doc, edited some bits and added some comments: https://docs.google.com/document/d/1Ybq_DonZqzX1vOrwxUmXC_ff9Yazdqn7ToEDVVay6ec/edit#

EoinShaughnessy commented 2 years ago

@vanitabarrett Doc is looking good! Just 3 dev comments to address - would you be able to take a look? Once we've resolved those, I can raise a PR to publish on GitHub.

lfdebrux commented 2 years ago

@vanitabarrett @EoinShaughnessy had a look over the doc, apart from a couple of small comments it looks good to me!

EoinShaughnessy commented 2 years ago

Thanks @lfdebrux!