Add guide for using GitHub Codespaces

[paulmsmith]

This PR is to add instructions for using the NHS Prototype Kit with Github Codespaces which is intended as a viable option for people who cannot (or would prefer not to) install the prototype kit on their computers.

It is contingent on a separate PR being merged to the prototype kit for a devcontainer to enable this.

Get started page

Setup the prototype kit on GitHub Codespaces

Step 1 - Create a Codespace

Step 2 - Working with Codespaces

[paulmsmith]

All comments, feedback welcome. I'm not the best writer and squeezed this in between other work.

[anandamaryon1]

Looks great, I'll give it a proper review asap (maybe next week though) and try to follow the instructions. Thanks for this 👍

[vickytnz]

I've suggested some changes (I probably should have done a PR)

1. I think our usual protocol is to try and lead with the action and then go into the platform so something like 'Install and use the kit with your web browser'
2. I've tried to do a bit of tweaking of text
3. I'm not sure what the deal will be if people need to commit code as we don't have that exactly in the install

Getting started

Start page

Page 1

Page 2

[paulmsmith]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

[vickytnz]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

sorry it's pushed to this branch, I haven't quite figured out how to do review changes from my laptop yet 🙈

[paulmsmith]

Do you have those changes in a branch @vickytnz? Just the type of feedback needed. I just whacked up an initial bunch of stuff to shape for the docs. :)

sorry it's pushed to this branch, I haven't quite figured out how to do review changes from my laptop yet 🙈

Oh I see. Didn't spot that, no worries that's all good.

[vickytnz]

The one thing that I missed when doing some rewrites was the balance of 'you can do this' and 'you can do this and the prototype kit has been set up to make it easy for you'- I kinda wrote it for the first option without thinking about the second. It could be something as simple as a line about 'For this tutorial we are using Codespaces. This is because it is it popular and part of Github. The prototype has built-in functionality to make it easy to connect to Codespaces' or similar.

[anandamaryon1]

Followed along and seems to work nicely. 👍

Minor comments:

• Where we first mention Codespaces and Gitpod, perhaps we should link to information about them (landing pages)?
• The Codespaces billing is quite complicated, maybe we should give a simple explanation for it, e.g (assuming we're 2 cores?) you'll be limited to around 60 hours per month, so consider whether this is enough for your needs. - a bit tricky since that could change beyond our control…
• Same issue for Gitpod, which is I think, around 50 hours per month. (https://www.gitpod.io/docs/configure/billing)
• Step 1.1: repo link, we should call this NHS Prototype Kit repository rather than NHSUK, to align with other docs
• Step 1.4: a screenshot here could be helpful too, so that users can understand that what they're looking at is correct and that it's all 'done' and running, and ready for the next step (since it's quite a complex interface and takes time to run)
• Step 2: save changes, second para's second sentence missing a space "changes with GitHub.You can use"
• Should take a look at where this guide should be linked into from other bits of the docs, eg. link from 'install on an NHSE laptop' and the 'install guide', as an alternative method

Happy to make these changes myself if you prefer @paulmsmith

Need a review from @sarawilcox and then we'll be good to go.

[anandamaryon1]

And another thing… 😃

I did a test push and it went into the nhsuk-prototype-kit repo, rather than a fork/clone of it.

• So I think this guide is missing the step where you clone the repo to your own Github account, then open a Codespace there, not on the main repo.

[sarawilcox]

Hi @paulmsmith, I just had a go at this and I think it's good! I made a teeny tweak to capitalisation just to check how things work. I'll come back to this PR over the next few days to review the content fully. For now, I just wanted to get an idea how it works from a user's point of view.

It works very similarly to GitPod so I was familiar with this sort of set up but it will be completely new for some people, especially content designers.

I think Codespaces won't just be for people who can't install software. It's probably also good for people who don't have strong technical skills and are finding it difficult to install the prototype kit (or something like that).

I can see people creating a Codespace following this guide, but then getting stuck on the editing/working with Codespaces page. The page goes into saving changes, managing prototypes etc. But I suspect non-specialists will need more help getting started. Just knowing:

• what they should expect to see on their screen
• where to find the files they'll be working on (for most content designers, it'll be app/views)
• that you can change the HTML and it will update in the browser, so you can see your changes as you work

The page points people off to https://docs.github.com/en/codespaces/getting-started/quickstart. But I'm struggling to understand that page. It's quite technical and the examples are not the sort that content designers can relate to.

I think people will need more help saving their changes and committing back to GitHub. Don't know if it helps to take them through the few key commands that I use as a content designer:

• git status
• git add .
• git commit -m "...."
• git push
  And to suggest that they ask the dev or designer in their team for help if they're having problems.

I'll feedback more comments when I do a proper content review. I'm wondering if @LauraJD would like to have a go at this as someone completely new to using the kit in the browser.

[frankieroberto]

@paulmsmith @anandamaryon1 @vickytnz I've made a few tweaks (mainly to remove the suggesting of using the 'Fork' button for now).

I think we could put this live, and then get some feedback on it from a few people who try it out?

[vickytnz]

I think we need to manage expectations about using Codespaces for now as without a template it's actually pretty hard to do new? It might be possible to do it somehow with visual studio code but it's going to need instructions that I can't quite figure out right now.

[vickytnz]

@frankieroberto sorry i'm still figuring out how to show changes in the code editor - you'll need to go and look at my actual code change, oops.

Actually it is this:

---

1. Go to the prototype repository

Go to the GitHub repository for the prototype you wish to use. For this guide we will be using the NHS prototype kit repository.

If you do not have a prototype repository

Is it not possible right now to install the kit in a new Github repository unless you can install software on your computer.

You can try using Codespaces using the NHS prototype kit repository. You will not be able to save your progress.

[anandamaryon1]

Made small content edits. I do think this is close now.

But some more general thoughts:

• The current guidance says we cannot create new repos with this method, “It is not possible right now to install the kit in a new Github repository…” this seems like quite a big blocker/caveat. I see that in Joe's guide he links to a template repo, perhaps we should get this sorted first, so that we can publish this without this blocker?
• The other blocker to starting a new prototype currently (not specific to codespaces though) is telling users where to store the prototypes. I'm not sure we know the answer yet, and it varies depending on where the user works, but feels like we need to provide some acknowledgement to this at least.
• And aside from these, I wonder whether we should reframe this guide away from ‘if you can’t install…’ to, "use the kit without installing anything on your device"? Since it's not strictly just for people who cannot install it on their device. Though fair enough if we keep it like this to begin with whilst we gain feedback, and then promote it more in future if it shows to be helpful.

[frankieroberto]

@anandamaryon1:

The current guidance says we cannot create new repos with this method, “It is not possible right now to install the kit in a new Github repository…” this seems like quite a big blocker/caveat. I see that in Joe's guide he links to a template repo, perhaps we should get this sorted first, so that we can publish this without this blocker?

There might be another way to do this. Maybe there's a way to upload a whole folder of files within the GitHub interface somehow? Or I guess people could use GitHub Desktop to upload the initial folder, if they can install that but can't easily install or use Node.js?

A template repo is worth exploring too though!

[anandamaryon1]

@frankieroberto Interesting! I hadn't thought of just dropping the files into the repo in the browser…

Have given it a try and it seems that when you download the repo as a .zip it doesn't include . files, such as .devcontainer, meaning it doesn't auto run in the codespace, and build fails when I try to npm install and npm run watch.

I also tried 'importing' the prototype kit repo into a fresh repo but it seem to be exactly the same as forking, where it brings over all of the Git history.

Possibly there's another way or a setting I've missed, but I couldn't get it working myself.

Update: tried making a fork of the proto repo in my own account, then turning that into a template repo and then making a new repo from that template but it keeps erroring… Maybe because it's weird that I'm trying to clone my own repo? Not sure what's going wrong though. If anyone else wants to try it, it's here: https://github.com/anandamaryon1/proto-template-test.git

Error page I get:

Another update: Think I've cracked it! What I did…

1. Click 'New codespace' from this page: https://github.com/codespaces
2. Select my template repo from the 'repository' list
3. Left other options default and clicked 'Create codespace'
4. Wait for Codespace to run/build (around 2 mins)
5. Make a change, commit and push it (publish branch, because it's a first push on main)
6. Get an alert that asks me to allow Github sign me in, click 'Allow'
7. Select my account from the dropdown that appears
8. Nothing seems to happen (but assume it signs me in in background), click 'Publish branch' again
9. Select public or private repo and edit the name (not intuitive, name defaults to template repo's name)
10. Upon pressing enter or clicking the public or private opotion, the push happens and it publishes a new repo

This seems like a good and fairly simple option, albeit that will require step by step instructions with screenshots as VScode isn't super intuitive.

One question remains, how does this work when publishing the prototype to an org Github account, rather than your own (which is not advised)?

[frankieroberto]

Blocked by #460

[anandamaryon1]

To add to this can of worms… I suppose another option is to make an npm package, similar to how gov do it? I'm not sure of the pros and cons to this though.

[frankieroberto]

To add to this can of worms… I suppose another option is to make an npm package, similar to how gov do it? I'm not sure of the pros and cons to this though.

I still think that could be an option for the future (as it'd make updates way easier) - but will take a fair bit of work. And even if we do that, then a template repo, which would include the kit via package.json would still be helpful?

[frankieroberto]

This bit can now be updated to mention using the 'Use this template' feature on the NHS prototype kit repo on GitHub.