Create new guidance that uses Visual Studio Code for everything

[vickytnz]

Visual Studio Code is a tool that has the potential to be the:

• text editor for code
• terminal for doing commands (this can be done in the application)
• git editor including connecting to Github (though pull requests need a separate plugin to properly work)

This will also mean that we have guidance that works for Codespaces (what people can use if they cannot install anything on their laptop).

Changing this will mean updating the:

1. install guide
2. basic prototype tutorial
3. github and github desktop tutorial - this will need a lot of rework as Github Desktop hides some terms like staging that are made visible again with Visual Studio Code

[vickytnz]

Note from experience using Visual Studio Code:

• the Github connection needs to be with SSH, otherwise it can break badly and pull requests won't work. The easiest way to fix this is to use the terminal command gh auth login, choose GitHub.com and SSH and follow the instructions
• changing branches is at the very bottom left
• the first time of using GitHub with visual studio code it will ask about staging code and if to ignore. this is hidden language in GitHub desktop, easiest to say 'yes'
• adding the GitHub Pull Requests extension helps with doing Pull Requests - it also opens the PR request in Visual Studio Code.

[vickytnz]

Extra notes with Visual Studio Code:

• merge conflicts are a bit scarier to navigate - it is kinda possible but isn't particularly intuitive (I accidentally merged all on one side whereas it's important to work down the list)

[anandamaryon1]

I like this idea, I've never used GitHub Desktop so I can't really comment on whether this is easier, but it would certainly make guidance simpler – fewer tools is usually a good thing.

Maybe if we were to go ahead with this we'd need to A/B test it with a few new folk?

[anandamaryon1]

I've never done PRs in VScode though, just making branches, commits and pushes, merge conflicts etc. To me, it seems to make sense to deal with things on the github website once they're in the repo, but maybe that's just me.

[vickytnz]

For install, the steps will probably be:

1. Software requirements

Install the following software:

• Node Package Manager (NPM)
• Node.JS (version 20 or later)
• Visual Studio Code - this is a combined code editor, terminal application, and git editor, and is free and well supported

If you are on a NHS Windows managed laptop download these from the software applications store.

2. Install the kit

Download the kit as a zip

The simplest way to get the kit is to download it as a zip.

You'll use a new copy of the kit for each new prototype you make. That way your prototypes don’t interfere with each other.

Make sure you are installing the kit on a local drive. Do not install the kit on a cloud-based drive (for example, Dropbox, Microsoft OneDrive), as this may cause permissions issues.

Make a folder for your prototypes

We recommend keeping all your prototypes in one folder.
If you are going to collaborate with others on your code, you will have all of your prototypes in a folder like GitHub. We will be calling our folder 'prototypes'.

Create a folder called prototypes in your Documents folder.

If you are on a NHS Windows managed machine

Within the root of your OneDrive create a new folder named DevWspace.

This folder name is on an approved list so you can create virtual environments and execute scripts.

The path should look like this after you have created it:

"C:\Users%username%\OneDrive - NHS\DevWspace"

Use this folder:

• for any prototypes that you make
• for any software for your kit that asks for a 'path' – ask a developer on your team if you need help

Unzip the kit and move it

Unzip the kit you downloaded - you should end up with a folder called nhsuk-prototype-kit followed by the version number.

Rename the folder to something descriptive for your prototype. For this guide, we’ll use magical-powers.

Move the folder into your prototypes folder.

Terminal basics

The terminal in Visual Studio Code (and in MacOS and Linux) lets you type in commands and run programs on your computer.

The important thing to remember about the terminal is that you‘re working in one directory (folder) at any one time.

There are a few commands you‘ll have to run in the terminal to use the Prototype Kit.

Commands

cd [name of directory] = change to [name of directory]
cd ~ = go to your home directory
ls = list all the folders and files in a directory
pwd = print working directory tells you what directory you’re in
press up and down on the keyboard to go through previous commands
npm start = start the Prototype Kit (you need to be in your prototype folder)
To quit the kit, in the terminal press the ctrl and c keys together.

If you type a command that the terminal does not understand, it will show you an error message. Do not worry if you see one of these. Have a look at the command you wrote and see if there is a typo in the command.

You can follow a tutorial on basic terminal commands on the codebar website.

Navigating to your prototype folder

You need to navigate to your prototype folder in the terminal. Most commands for the kit need to be run in the prototype folder. If you are using Visual Studio Code,

cd ~/Documents/prototypes/magical-powers
Take note of what is upper or lower case - for example lower case 'd' for 'Documents' will not work.

If any of your folder names contain spaces, you must add quotation marks around everything after ~/. For example:

cd ~/"a folder name with spaces/Documents/prototypes/magical-powers"
Install modules
You need to download extra code used by the kit before it can run. You only need to run this command the first time you start or download a prototype:

npm install
The install may take about a minute. Whilst installing, it may WARN about some items - this is ok. As long as there are no ERRORs, you can continue.

3. Run the kit

You’ll use the terminal to start and stop the kit.

Open the prototype folder in terminal
If you're following the installation guide, you'll already have the terminal open in the right folder.

If you're coming back to work on a prototype, you'll need to navigate to the folder:

cd ~/Documents/prototypes/magical-powers
Or replace 'magical-powers' with the name of your prototype.

Running the kit

In the terminal, enter:

npm start
The first time you run npm start, the kit will ask you whether you want to send anonymous data to help the team improve the service. Enter y or n to answer yes or no.

After the kit has started, you should see a message telling you that the kit is running:

Listening on port 3000 url: http://localhost:3000

Check it works

In your web browser, open http://localhost:3000 (opens in a new tab)

Screenshot of what your prototype homepage should look like.

Quitting the kit

It’s fine to leave the kit running for days or while your computer is asleep.

To quit the kit, in the terminal press the ctrl and c keys together.

Installation complete
The kit is now installed. Congratulations!

Make your first prototype

You can now start the tutorial to make your first prototype or view other guides.

[edwardhorsford]

I've always thought (suspected) that Github Desktop / a GUI is easier for people new to git - you click on the things you want to commit, it guides you though quite a few of the actions. Would this imply only teaching command line usage?