Make it easier to update the kit

[frankieroberto]

Currently, the update instructions for the kit involve downloading a new copy, copying across some of the files and folders, and manually merging any changes you’ve made to key files such as config.js and main.scss.

We should look at a range of ways to potentially make this easier.

Some initial ideas (in order of effort):

• Make the current manual copy-and-paste option easier by having as many of the files as possible in a single folder to copy across (eg kit/) rather than everything-except-app/
• Write an update script which could download the latest version and do the copying-and-pasting for you
• Move the bulk of the kit into a published Node.js package so that it can be updated using node package manager (NPM) in the same way as NHS Frontend and other dependencies

[frankieroberto]

Any thoughts @edwardhorsford @paulmsmith @paulrobertlloyd @vickytnz @mikemonteith?

[vickytnz]

I don't know how easy it is to do 2 or 3, but I think that it's far more likely to encourage uptake, particularly if we start adding a lot more changes at pace? Defo one to sense check with the service manual team but this feels like one that could really help encourage people to use it (especially as it could also help with first-time installs)

[mikemonteith]

To make upgrades easier, a bundled npm package approach would be good, but the tradeoff is that it becomes a lot harder to modify the behaviour of the internal prototype kit code if you need to do that for whatever reason.

Do we want to discourage people hanging on to prototypes for a long time and having to maintain them? The point of this kit is that you can quickly create something and throw it away?

[vickytnz]

I think that this comes to who we optimise for:

1. people who will get discouraged at doing installs and upgrades and fall back to using figma
2. people maintaining existing kits who have done customisations who will get annoyed at it being harder to maintain customisations

My hunch is to optimise for group 1 and help group 2 with support - especially if we are bringing parity to the NHS frontend and the design system and rapidly bringing in new components?

Though perhaps to Mike's point - are we ok with multiple heroku and github repos if need be? (I do also have a bias about versioning from when I started as a UR and in the absence of design histories versioned prototypes are a lot easier for archaeology - this is probably another note about the multiple purposes of prototypes both as being things used in the moment and also being used as snapshots).

[paulrobertlloyd]

Anecdotally, I’ve heard people get confused with the GOV.UK Prototype Kit as it's a bit of an opaque box, and difficult to know where certain files (like layouts) are coming from (and once you do release its coming from the package(s), still unclear where in the/which package a particular file is saved).

I like the idea of one folder, that you can copy across to update.

The other challenge is, the repo for the kit contains lots of code useful for developing the kit, which isn’t necessary for using the kit. I wonder if there’s a way to abstract away some of that stuff?

[joelanman]

if you're considering 3, I would suggest forking the GOV.UK kit and using NHS styles instead

[joelanman]

the repo for the kit contains lots of code useful for developing the kit, which isn’t necessary for using the kit. I wonder if there’s a way to abstract away some of that stuff?

its common to have a release process, that puts files in a dist folder, which is what gets released - GOV.UK Frontend does this

[edwardhorsford]

if you're considering 3, I would suggest forking the GOV.UK kit and using NHS styles instead

I think we'd want to make sure it uses the NHS Design system components too.

The point of this kit is that you can quickly create something and throw it away?

I guess it depends on the prototype. I've often had prototypes that are more long lived / get much more complex and detailed as beta progresses. I don't usually bother updating them though.

To make upgrades easier, a bundled npm package approach would be good, but the tradeoff is that it becomes a lot harder to modify the behaviour of the internal prototype kit code if you need to do that for whatever reason.

As an advanced user I avoided v13 onwards of the GOV.UK prototype kit as I'm someone who wants to modify the behaviour of things. I've appreciated having full control in the NHS kit. I'm very much an advanced user though and most likely never touch things outside of app.

[joelanman]

yeh sorry I meant all NHS stuff, not GOV UK stuff

[joelanman]

also, there's an inherent tension between 'changing anything in any part of the kit' and 'easy to update'. We certainly saw vastly improved update figures when we moved to a module

[frankieroberto]

Definitely some trade-offs! I guess in theory you can mitigate the need to edit the code running the kit itself by adding various hooks or configuration options - but then it’s hard to know in advance which options people might need?

@paulrobertlloyd:

The other challenge is, the repo for the kit contains lots of code useful for developing the kit, which isn’t necessary for using the kit. I wonder if there’s a way to abstract away some of that stuff?

Did you mean the NHS or GOVUK kit here, or both?

For the NHS kit, I wonder whether a good starting point would be to move towards having a single folder (named kit or lib?) with nearly all the code, suggest that users avoid editing anything in it, and then at least in the short term the upgrade instructions could be simpler (download zip and copy across a single folder)?

Then longer-term we could consider moving that to an npm package for even easier updates?

[paulrobertlloyd]

Did you mean the NHS or GOVUK kit here, or both?

The NHS kit. I count 12 files in the project root that are potentially not very useful for end users. More a cleanliness/tidyiness thing, though possibly confusing for some.

Also, can the /docs folder now be removed?

I wonder whether a good starting point would be to move towards having a single folder

I’d absolutely recommend starting small, and get things into a sensible order before thinking about doing anything more complicated.

[frankieroberto]

Did you mean the NHS or GOVUK kit here, or both?

The NHS kit. I count 12 files in the project root that are potentially not very useful for end users. More a cleanliness/tidyiness thing, though possibly confusing for some.

I guess this is an inevitable downside of people downloading the whole thing (either via zip file or git clone) - some of the files are for development rather than for kit users.

I did have a Quick Look to see if there’s a way to tell GitHub to exclude some files from the assets zip on release pages like 5.1.0 but couldn’t see anything. We could have a separate release step to bundle up files into a dist/ folder and then zip that up – but it’d be an additional step I think? Could be an intermediate step before doing a full npm package release though? 🤔

Also, can the /docs folder now be removed?

Not quite yet. It still has the example templates in it. Need to consider what to do with those - see nhsuk/nhsuk.service-manual.prototype-kit.docs#60

The docs folder also contains the main layout file used by the app, with the <html> tag and so on, which is pretty confusing. I was thinking of moving it to app/ in #395 but then @edwardhorsford convinced me otherwise. I think longer-term it should be moved to the nhuk-frontend npm package instead, in the same way as the govuk one.

I wonder whether a good starting point would be to move towards having a single folder

I’d absolutely recommend starting small, and get things into a sensible order before thinking about doing anything more complicated.

Agreed. I think the next logical steps are to complete the tasks to remove docs/ and then see if the code currently in middlewares and lib could be merged into a single folder?

[frankieroberto]

Have made a first step towards consolidating files within lib in #409.