CCM-16446 updating readme guidence

README.md

@@ -1,140 +1,44 @@
 # NHS Notify Web CMS Repository
 
-[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=repository-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=repository-template)
+[![CI/CD Pull Request](https://github.com/NHSDigital/nhs-notify-web-cms/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/NHSDigital/nhs-notify-web-cms/actions/workflows/cicd-1-pull-request.yaml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=NHSDigital_nhs-notify-web-cms&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=NHSDigital_nhs-notify-web-cms)
 
 ## About this project
 
-- This site includes the content for the public NHS Notify web site
+- This site includes the content for the public [N]HS Notify web site](https://notify.nhs.uk/)
 - It uses Jekyll to generate static web HTML files from markdown content
-- the source code for the web site is in /docs folder
-- page content is inside the `/docs/pages` folder
-- page css is inside `/docs/_sass` folder
-
-## Getting Started - First time setup
-
-This is only needed once.
-
-To get started, please create a new GitHub workspace from the main branch.
-
-This will setup a development environment for you to edit the web site in. The first time this runs, it will take approximately 10 minutes. You do not need to install ANY tools on your local computer.
+- The source code for the web site is in `/docs` directory
+- Page content is inside the `/docs/pages` directory
+- Page CSS is inside `/docs/_sass` directory
+- The webpage is published to GitHub Pages using [this GitHub Actions workflow](.github/workflows/jekyll-gh-pages.yml)
 
 ### Pre-requisites
 
 - A GitHub account
-- For submitting changes, code must be signed.
-- To sign code using GitHub code spaces, please configure GPG signing for the repository, from your Settings page.
-
-### 1. From a web browser, visit the Web CMS GitHub Repository page
-
-[https://github.com/NHSDigital/nhs-notify-web-cms](https://github.com/NHSDigital/nhs-notify-web-cms)
-
-### 2. Click Code
-
-Click the green `<> Code` button.
-
-![alt text](assets/img/image.png)
-
-### 3. Create Codespace on main
-
-Click create code space on main
-
-![alt text](assets/img/image-1.png)
-
-### 4. Wait
-
-- a new browser tab should open
-- you will need to wait around 5 - 10 minutes
-
-When it first starts it will look something like this. At it will say opening remote at the bottom left.
-
-![alt text](assets/img/image-2.png)
-
-### 5. Launch workspace
-
-You will see a box pop up bottom right notifying you there is a workspace file.
-
-- click the Green button to `Open Workspace`
-
-![alt text](assets/img/image-3.png)
-
-### 6 . Open parent git repository
-
-Another box will pop up saying a parent git repository has been found. Click the Green `Yes` button to open it.
-
-![alt text](assets/img/image-4.png)
-
-An option should appear at the top of the screen, select the `nhs-notify-web-cms` repository.
-
-![alt text](assets/img/image-5.png)
-
-### 5. Test it works
-
-You should be able to run a live version of your changes before you submit them (via a Pull request) for updating the live content.
-
-To do this, click the Run and Debug button, and then click the "Play" icon. Alternatively you can press F5 (warning, if you are not "clicked" in the window, it will refresh your page instead of launching the site).
-
-- click the run and debug button:
-
-![alt text](assets/img/image-6.png)
-
-- click the green "Play" button to the left of where it says `Attach (NHS Notify`
-
-![alt text](assets/img/image-7.png)
-
-- after a few seconds, you should see moving text at the bottom of the screen and it say `server running`
-
-![alt text](assets/img/image-8.png)
-
-- a box should appear bottom right saying your application is running. Click the green `Open in browser button`
-
-![alt text](assets/img/image-9.png)
-
-- a new browser tab will open (with a random address), this is live updating as you change the content of the site.
-
-![alt text](assets/img/image-10.png)
-
-### 6. Make a preview change
-
-- In the previous browser tab, click on the file `Explorer` button to show the file list.
-
-![alt text](assets/img/image-11.png)
-
-- Click on the `pages` folder, and then `index.md`. This will open the content of the home page.
-
-![alt text](assets/img/image-12.png)
-
-- you can now edit this page. To see a basic preview side by side, click the markdown preview button
-
-![alt text](assets/img/image-13.png)
-
-- this will open a preview to the right
-
-![alt text](assets/img/image-14.png)
-
-- If you now edit some text in the left, it will update in the basic preview on the right in real time. If you click `File` - `Save` (or `Ctrl-S`) this will save the file.
-
-- Saving the file will update the Full preview site in the other browser tab.
-
-- Open the other tab, and Press `F5` to refresh the page.
+- For submitting changes; [**code must be signed** with a GPG key](setup/gpg.md) linked to your GitHub account.
 
-### 7. Making a change permanent and live
+#### Setup guides
 
-You must:
+- [GPG setup for Codespaces](setup/gpg.md)
+- [First-time Codespaces setup](setup/codespaces.md)
+- [GitHub Copilot quick start](setup/copilot.md)
+- [FAQ](setup/faq.md)
 
-- create a new branch in your workspace
-- commit the changes to your new branch
-- push (publish) the new branch to your remote
-- create a Pull Request for requesting that your remote branch is merged into main
-- await approval
+### Making a changes checklist
 
-## Making further changes
+- Create a new branch in your workspace
+- Commit the changes to your new branch
+- Push (publish) the new branch to your remote
+- Create a Pull Request for requesting that your remote branch is merged into main
+- Seek and await approvals
+- Do not merge changes if all checks or are not passing.
+  ![Screenshot of a PR failing](assets/img/README-pr-review.png)
 
-### Open existing CodeSpaces
+### Open existing Codespaces
 
-- You can reuse existing CodeSpaces that have been setup.
-- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of code spaces
-- Active code spaces are charged. Everyone gets 150 hours free per month.
+- You can reuse existing Codespaces that have been setup.
+- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of Codespaces
+- Active Codespaces are charged. Everyone gets 150 hours free per month.
 - Click on the `three dots` and then click `stop codespace` to change it to inactive
-- A stopped code space does not loose data
-- You can delete a CodeSpace, but this will loose any data that you have not pushed (published) to a remote git branch.
+- A stopped code space does **not** loose data
+- You can delete a Codespace, but this **will** loose any data that you have not pushed (published) to a remote git branch.

scripts/config/pre-commit.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/NHSDigital/nhs-notify-shared-modules
-    rev: 3.0.9
+    rev: 3.1.2
     hooks:
       - id: scan-secrets
         args: [check=staged-changes]

scripts/config/sonar-scanner.properties

@@ -4,6 +4,8 @@ sonar.host.url=https://sonarcloud.io
 sonar.qualitygate.wait=true
 sonar.sourceEncoding=UTF-8
 sonar.sources=.
+sonar.coverage.exclusions=**/*
+sonar.cpd.exclusions=**/*
 
 #sonar.python.coverage.reportPaths=.coverage/coverage.xml
 #sonar.[javascript|typescript].lcov.reportPaths=.coverage/lcov.info

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -2,21 +2,26 @@
 [cC]yber
 [iI]nset
 [Uu][Rr][Ll]
+ad-hoc
 APIM
 Bitwarden
 bot
 bundler
 Burkina
 clientRef
+Codespace
+Codespaces
 Cohorting
 ctrl
 Dependabot
 endfor
+Fireship
 fullName
 Futuna
 Gitleaks
 Grype
 idempotence
+J[Ii][Rr][Aa]
 Maarten
 Marino
 namePrefix
@@ -33,6 +38,7 @@ Podman
 precompiled
 Python
 realtime
+rebasing
 Rica
 rollout
 Sao
@@ -49,4 +55,5 @@ Trufflehog
 unnotified
 urlset
 validation_failed
+VSCode
 Wayfinder

setup/codespaces.md

@@ -0,0 +1,105 @@
+# First-Time Codespaces Setup
+
+Use this guide for first-time setup in GitHub Codespaces.
+
+## 1. From a web browser, visit the Web CMS GitHub Repository page
+
+[https://github.com/NHSDigital/nhs-notify-web-cms](https://github.com/NHSDigital/nhs-notify-web-cms)
+
+## 2. Click Code
+
+Click the green `<> Code` button.
+
+<img src="../assets/img/image.png" alt="Click Code" width="500"/>
+
+## 3. Create Codespace on main
+
+Click create code space on main
+
+<img src="../assets/img/image-1.png" alt="Create Codespace on main" width="500"/>
+
+## 4. Wait
+
+- a new browser tab should open
+- you will need to wait around 5 - 10 minutes
+
+When it first starts it will look something like this. At it will say opening remote at the bottom left.
+
+<img src="../assets/img/image-2.png" alt="Codespace starting up" width="500"/>
+
+## 5. Launch workspace
+
+You will see a box pop up bottom right notifying you there is a workspace file.
+
+- click the Green button to `Open Workspace`
+
+<img src="../assets/img/image-3.png" alt="Open Workspace button" width="500"/>
+
+## 6. Open parent git repository
+
+Another box will pop up saying a parent git repository has been found. Click the Green `Yes` button to open it.
+
+<img src="../assets/img/image-4.png" alt="Parent repository dialog" width="500"/>
+
+An option should appear at the top of the screen, select the `nhs-notify-web-cms` repository.
+
+<img src="../assets/img/image-5.png" alt="Select repository option" width="500"/>
+
+## Confirm it works
+
+You should be able to run a live version of your changes before you submit them (via a Pull request) for updating the live content.
+
+To do this, click the Run and Debug button, and then click the "Play" icon. Alternatively you can press F5 (warning, if you are not "clicked" in the window, it will refresh your page instead of launching the site).
+
+- click the run and debug button:
+
+<img src="../assets/img/image-6.png" alt="Run and Debug button" width="500"/>
+
+- click the green "Play" button to the left of where it says `Attach (NHS Notify`
+
+<img src="../assets/img/image-7.png" alt="Play button" width="500"/>
+
+- after a few seconds, you should see moving text at the bottom of the screen and it say `server running`
+
+<img src="../assets/img/image-8.png" alt="Server running message" width="500"/>
+
+- a box should appear bottom right saying your application is running. Click the green `Open in browser button`
+
+<img src="../assets/img/image-9.png" alt="Open in browser button" width="500"/>
+
+- a new browser tab will open (with a random address), this is live updating as you change the content of the site.
+
+<img src="../assets/img/image-10.png" alt="Live updating website" width="500"/>
+
+## Make a preview change
+
+- In the previous browser tab, click on the file `Explorer` button to show the file list.
+
+<img src="../assets/img/image-11.png" alt="File Explorer button" width="500"/>
+
+- Click on the `pages` folder, and then `index.md`. This will open the content of the home page.
+
+<img src="../assets/img/image-12.png" alt="Pages folder and index.md" width="500"/>
+
+- you can now edit this page. To see a basic preview side by side, click the markdown preview button
+
+<img src="../assets/img/image-13.png" alt="Markdown preview button" width="500"/>
+
+- this will open a preview to the right
+
+<img src="../assets/img/image-14.png" alt="Preview panel" width="500"/>
+
+- If you now edit some text in the left, it will update in the basic preview on the right in real time. If you click `File` - `Save` (or `Ctrl-S`) this will save the file.
+
+- Saving the file will update the Full preview site in the other browser tab.
+
+- Open the other tab, and Press `F5` to refresh the page.
+
+## Open existing Codespaces
+
+- You can reuse existing Codespaces that have been setup.
+- Visit [https://github.com/codespaces](https://github.com/codespaces) to see a list of Codespaces
+- Active Codespaces are charged. Everyone gets 150 hours free per month.
+- Click on the `three dots` and then click `stop codespace` to change it to inactive
+- A stopped code space does **not** loose data
+- You can delete a Codespace, but this **will** loose any data that you have not pushed (published) to a remote git branch.

setup/copilot.md

@@ -0,0 +1,11 @@
+# GitHub Copilot Quick Start
+
+GitHub Copilot is available inside your Codespace and can help you draft, edit, and improve content faster.
+<img src="../assets/img/copilot-howto.png" alt="Copilot" width="300"/>
+
+## Recommended guidance
+
+For team guidance on safe and effective AI use, read:
+
+- [NHS Engineering AI Coding Assistant User Guide](https://nhs.sharepoint.com/sites/X26_EngineeringCOE/SitePages/AI-Coding-Assistants---User-Guide.aspx?web=1&isSPOFile=1&ovuser=37c354b2-85b0-47f5-b222-07b48d774ee3%2Caiden.vaines2%40nhs.net&OR=Teams-HL&CT=1777458253077&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiI1MC8yNjA0MDQwMTcxOCIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D&linkOpenTime=1777458253084)
+- [Making the best use of AI](https://nhsd-confluence.digital.nhs.uk/spaces/RIS/pages/1336633374/Team+SKYNET+Making+the+best+use+of+AI)