Merge pull request #133 from NHSDigital/docs/NPA-3901_update_project_documentation

JackPlowman · web-flow · commit 740ff01d8865 · 2024-12-04T11:48:27.000Z
NPA-3901 Improve Project Documentation
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,17 +1,17 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,15 +24,17 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser: [e.g. chrome, safari]
- - Version: [e.g. 22]
+
+-   OS: [e.g. iOS]
+-   Browser: [e.g. chrome, safari]
+-   Version: [e.g. 22]
 
 **Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser: [e.g. stock browser, safari]
- - Version: [e.g. 22]
+
+-   Device: [e.g. iPhone6]
+-   OS: [e.g. iOS8.1]
+-   Browser: [e.g. stock browser, safari]
+-   Version: [e.g. 22]
 
 **Additional context**
 Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,10 +1,9 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
 
 **Is your feature request related to a problem? Please describe.**
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -3,6 +3,7 @@
 ## Ticket Link
 
 <!-- Add the Jira ticket link here -->
+
 https://nhsd-jira.digital.nhs.uk/browse/NPA-XXXX
 
 ## Description/Change Summary
@@ -14,6 +15,7 @@ https://nhsd-jira.digital.nhs.uk/browse/NPA-XXXX
 -
 
 # How to test?
+
 <!--- Describe in detail how you tested your changes -->
 <!--- Include details of your testing environment and the tests you ran to see how your change affects other areas of the code etc. -->
 <!--- Are there any automated tests that mean changes don't need to be manually changed? -->
@@ -29,8 +31,9 @@ Stages to complete before opening the Pull Request:
 -->
 
 ## Review Checklist
+
 :information_source: This section is to be filled in by the **reviewer**.
 
-* [ ] I have reviewed the changes in this PR and they fill all or part of the acceptance criteria of the ticket, and the code is in a mergeable state.
-* [ ] If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
-* [ ] I have ensured the changelog has been updated by the submitter, if necessary.
+-   [ ] I have reviewed the changes in this PR and they fill all or part of the acceptance criteria of the ticket, and the code is in a mergeable state.
+-   [ ] If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
+-   [ ] I have ensured the changelog has been updated by the submitter, if necessary.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -11,7 +11,7 @@ appearance, race, religion, or sexual identity and orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
+Examples of behaviour that contributes to creating a positive environment
 include:
 
 -   Using welcoming and inclusive language
@@ -20,7 +20,7 @@ include:
 -   Focusing on what is best for the community
 -   Showing empathy towards other community members
 
-Examples of unacceptable behavior by participants include:
+Examples of unacceptable behaviour by participants include:
 
 -   The use of sexualized language or imagery and unwelcome sexual attention or
     advances
@@ -34,8 +34,8 @@ Examples of unacceptable behavior by participants include:
 ## Our Responsibilities
 
 Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+behaviour and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behaviour.
 
 Project maintainers have the right and responsibility to remove, edit, or
 reject comments, commits, code, wiki edits, issues, and other contributions
@@ -54,7 +54,7 @@ further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
 reported by contacting the project team. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,11 +1,18 @@
 # Contribution Guidelines
 
+> [!WARNING]
+> Some of the documentation and links in this file are specific to the maintainers of this repository and are only available to NHS England staff.
+
 -   [Contribution Guidelines](#contribution-guidelines)
     -   [Raising an Issue](#raising-an-issue)
     -   [Contributing code](#contributing-code)
         -   [Merge responsibility](#merge-responsibility)
         -   [Branch naming](#branch-naming)
+            -   [Developers within the NHS](#developers-within-the-nhs)
+            -   [Developers outside of the NHS](#developers-outside-of-the-nhs)
         -   [Commit messages](#commit-messages)
+            -   [Developers within the NHS](#developers-within-the-nhs-1)
+            -   [Developers outside of the NHS](#developers-outside-of-the-nhs-1)
 
 ## Raising an Issue
 
@@ -28,14 +35,25 @@ so please explain why the changes need to be made (unless it is self-evident).
 
 ### Branch naming
 
+#### Developers within the NHS
+
 Branch names should be of the format:
 
-`apm-nnn-short-issue-description`
+`NPA-nnnn_short_issue_description`
+e.g. `NPA-1234_update_readme`
 
 Multiple branches are permitted for the same ticket.
 
+#### Developers outside of the NHS
+
+Branch names should be of the format:
+
+`short_issue_description`
+
 ### Commit messages
 
+#### Developers within the NHS
+
 Commit messages should be formatted as follows:
 
 ```
@@ -44,3 +62,14 @@ APM-NNN Summary of changes
 Longer description of changes if explaining rationale is necessary,
 limited to 80 columns and spanning as many lines as you need.
 ```
+
+#### Developers outside of the NHS
+
+Commit messages should be formatted as follows:
+
+```
+Summary of changes
+
+Longer description of changes if explaining rationale is necessary,
+limited to 80 columns and spanning as many lines as you need.
+```
diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md
@@ -3,31 +3,31 @@
 This documentation is intended for developers to develop the schema, sandbox and proxies. It may be used by developers working within the NHS Digital organisation and outside contributors.
 
 > [!WARNING]
-> Some of the documentation and links are specific to the maintainers of this repository and are only available to NHS England staff.
+> Some of the documentation and links in this file are specific to the maintainers of this repository and are only available to NHS England staff.
 
 ## Table of Contents
 
-- [Development Guide](#development-guide)
-  - [Table of Contents](#table-of-contents)
-  - [Development](#development)
-    - [Requirements](#requirements)
-    - [Make commands](#make-commands)
-    - [Testing](#testing)
-    - [Platform setup](#platform-setup)
-    - [Detailed folder walk through](#detailed-folder-walk-through)
-      - [`/.github`:](#github)
-      - [`/azure`:](#azure)
-      - [`/proxies`:](#proxies)
-      - [`/scripts`:](#scripts)
-      - [`/specification`:](#specification)
-      - [`/tests`:](#tests)
-      - [`Makefile`:](#makefile)
-      - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml)
-      - [`manifest_template.yml`:](#manifest_templateyml)
-  - [Releasing a new schema version](#releasing-a-new-schema-version)
-    - [Caveats](#caveats)
-      - [Swagger UI](#swagger-ui)
-      - [Apigee Portal](#apigee-portal)
+-   [Development Guide](#development-guide)
+    -   [Table of Contents](#table-of-contents)
+    -   [Development](#development)
+        -   [Requirements](#requirements)
+        -   [Make commands](#make-commands)
+        -   [Testing](#testing)
+        -   [Platform setup](#platform-setup)
+        -   [Detailed folder walk through](#detailed-folder-walk-through)
+            -   [`/.github`:](#github)
+            -   [`/azure`:](#azure)
+            -   [`/proxies`:](#proxies)
+            -   [`/scripts`:](#scripts)
+            -   [`/specification`:](#specification)
+            -   [`/tests`:](#tests)
+            -   [`Makefile`:](#makefile)
+            -   [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml)
+            -   [`manifest_template.yml`:](#manifest_templateyml)
+    -   [Releasing a new schema version](#releasing-a-new-schema-version)
+        -   [Caveats](#caveats)
+            -   [Swagger UI](#swagger-ui)
+            -   [Apigee Portal](#apigee-portal)
 
 ## Development
 
diff --git a/README.md b/README.md
@@ -1,14 +1,14 @@
-# validated-relationships-service-api
+# Validated Relationship Service API
 
-This is a RESTful FHIR API for the [Validated Relationship Service API](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service).
+This is a RESTful FHIR API for the [Validated Relationship Service](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service).
 
 Consumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service).
 
 This repository does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Proxy Validated Relationship Service' repository which is not currently open source.
 
 ## Table of Contents
 
--   [validated-relationships-service-api](#validated-relationships-service-api)
+-   [Validated Relationship Service API](#validated-relationship-service-api)
     -   [Table of Contents](#table-of-contents)
     -   [Repository Structure](#repository-structure)
     -   [Contributing](#contributing)
@@ -19,8 +19,8 @@ This repository does _not_ include the Validated Relationship Service FHIR API b
 
 This repository includes:
 
--   [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) - The [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers.
--   `sandbox/` - A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing.
+-   [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) - The [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Used to generate interactive documentation for the NHS API Catalogue; the contract between the API and its consumers.
+-   `sandbox/` - A flask (Python) API that implements a mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing.
 -   `scripts/` - Utilities helpful to developers for the development and release of the specification.
 -   `proxies/` - Live and sandbox Apigee API Proxy definitions.
 
@@ -30,7 +30,7 @@ Contributions to this project are welcome from anyone, providing that they confo
 
 ## Development & Testing
 
-All development commands and documentation can be found in [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md).
+Development documentation can be found in [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md).
 
 ### Licensing
 
diff --git a/postman/README.md b/postman/README.md
@@ -0,0 +1,8 @@
+# Postman Collection
+
+This folder contains the Postman collection for the API.
+
+> [!WARNING]
+> Documentation and links in this file are specific to the maintainers of this repository and are only available to NHS England staff.
+
+To update the Postman collection follow the steps on the [How to update Postman Collection Confluence page](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=874694621)
diff --git a/sandbox/Makefile b/sandbox/Makefile
@@ -4,7 +4,7 @@ dirname := $(notdir $(patsubst %/,%,$(CURDIR)))
 install: # Installs dependencies using poetry.
 	poetry install --no-root
 
-list:
+list: # List of make targets
 	@grep '^[^#[:space:]].*:' Makefile
 
 build: # Build the Docker image to simulate ECS build
diff --git a/sandbox/README.md b/sandbox/README.md
@@ -6,17 +6,28 @@ For more information about building sandbox APIs see the [API Producer Zone conf
 
 ## Table of Contents
 
--   [Sandbox](#sandbox)
-    -   [Table of Contents](#table-of-contents)
-    -   [Prerequisites](#prerequisites)
-    -   [Quick Start](#quick-start)
-        -   [Installing dependencies](#installing-dependencies)
-        -   [Starting the API](#starting-the-api)
-    -   [Development](#development)
-        -   [Starting the API with Hot Reloading](#starting-the-api-with-hot-reloading)
-        -   [Testing](#testing)
-            -   [Unit Tests](#unit-tests)
-        -   [Useful commands](#useful-commands)
+- [Sandbox](#sandbox)
+  - [Table of Contents](#table-of-contents)
+  - [Architecture](#architecture)
+  - [Prerequisites](#prerequisites)
+  - [Quick Start](#quick-start)
+    - [Installing dependencies](#installing-dependencies)
+    - [Starting the API](#starting-the-api)
+  - [Development](#development)
+    - [Starting the API with Hot Reloading](#starting-the-api-with-hot-reloading)
+    - [Testing](#testing)
+      - [Unit Tests](#unit-tests)
+    - [Useful commands](#useful-commands)
+
+## Architecture
+
+The sandbox API is built using Python 3.8 and [Flask](https://flask.palletsprojects.com/en/stable/).
+
+The API is able to be run locally on the host system for development and testing purposes.
+
+The Sandbox is deployed using Docker to AWS ECS; the Dockerfile is located in the root of the repository. This allows Docker to copy in responses from `specification/examples/responses`. The docker container is deployed to AWS ECS using Azure DevOps pipelines.
+
+The [Postman Collection](./postman/Validate_Relationship_Service_Sandbox.postman_collection.json) is used to test the Sandbox API. The tests embedded in the collection are run in GitHub Actions on each Pull Request.
 
 ## Prerequisites
 
@@ -26,17 +37,23 @@ For more information about building sandbox APIs see the [API Producer Zone conf
 
 ## Quick Start
 
-Please note all commands are meant to be run from this directory `/sandbox`
+Please note all make targets commands are meant to be run from this directory `/sandbox`
 
 ### Installing dependencies
 
-To install the dependencies use `make install`
+To install the sandbox dependencies use `make install`
 
-If you do not have poetry installed you can install the dependencies using `pip install poetry` and then run `make install`
+If you do not have poetry installed you can install the dependencies using `pipx install poetry` and then run `make install`
 
 ### Starting the API
 
-To start the API locally use `make start`
+To start the API locally use the following command:
+
+```bash
+make start
+```
+
+The API will be available at [http://localhost:9000](http://localhost:9000)
 
 ## Development
 
