Docs: [AEA-0000] - improve documentation (#52)

## Summary

- Routine Change

### Details

- update readme
- update pull request template
- update contributing
- update release

Author: anthony-nhs

.github/pull_request_template.md

@@ -33,6 +33,11 @@ Tag can be one of:
 - `Upgrade` - for a dependency upgrade. (Patch release)
 - `Chore` - for refactoring, adding tests, etc. (anything that isn't user-facing). (Patch release)
 
+If the current release is x.y.z then
+- a patch release increases z by 1
+- a minor release increases y by 1
+- a major release increases x by 1
+
 Correct tagging is necessary for our automated versioning and release process ([Release](./RELEASE.md)).
 
 The description of your pull request will be used as the commit message for the merge, and also be included in the changelog. Please ensure that your title is sufficiently descriptive.

CONTRIBUTING.md

@@ -1,38 +1,68 @@
 # Contribution Guidelines
 
 ## Raising an Issue
+
 If you raise an issue against this repository, please include as much information as possible to reproduce any bugs,
 or specific locations in the case of content errors.
 
 ## Contributing code
+
 To contribute code, please fork the repository and raise a pull request.
 
 Ideally pull requests should be fairly granular and aim to solve one problem each. It would also be helpful if they
 linked to an issue. If the maintainers cannot understand why a pull request was raised, it will be rejected,
 so please explain why the changes need to be made (unless it is self-evident).
 
 ### Merge responsibility
-* It is the responsibility of the reviewer to merge branches they have approved.
-* It is the responsibility of the author of the merge to ensure their merge is in a mergeable state.
-* It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible.
+
+- It is the responsibility of the reviewer to merge branches they have approved.
+- It is the responsibility of the author of the merge to ensure their merge is in a mergeable state.
+- It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible.
 
 ### Branch naming
+
 Branch names should be of the format:
 
-`apm-nnn-short-issue-description`
+`aea-nnn-short-issue-description`
 
 Multiple branches are permitted for the same ticket.
 
 ### Commit messages
+
 Commit messages should be formatted as follows:
-```
-APM-NNN Summary of changes
+
+```text
+AEA-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.
 ```
 
+Commits from a pull request get squashed into a single commit on merge, using the pull request title as the commit message.
+Please format your pull request title using tags from [ESLint Convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) as follows:
+
+```text
+Tag: [AEA-NNNN] - Short description
+```
+
+Tag can be one of:
+
+- `Fix` - for a bug fix. (Patch release)
+- `Update` - either for a backwards-compatible enhancement or for a rule change that adds reported problems. (Patch release)
+- `New` - implemented a new feature. (Minor release)
+- `Breaking` - for a backwards-incompatible enhancement or feature. (Major release)
+- `Docs` - changes to documentation only. (Patch release)
+- `Build` - changes to build process only. (No release)
+- `Upgrade` - for a dependency upgrade. (Patch release)
+- `Chore` - for refactoring, adding tests, etc. (anything that isn't user-facing). (Patch release)
+
+If the current release is x.y.z then
+- a patch release increases z by 1
+- a minor release increases y by 1
+- a major release increases x by 1
+
+Correct tagging is necessary for our automated versioning and release process ([Release](./RELEASE.md)).
+
 ### Changelog
-Every pull request must include a change to the changelog.
 
-Add changes to the top of the current date. If the date is old, the reviewer should update the changelog to be correct before merging.
+Release changelogs are generated from the titles of pull requests merged into the `main` branch. Please ensure that your pull request title is sufficiently descriptive of the changes made.

README.md

@@ -1,6 +1,8 @@
 # eps-FHIR-validator-lambda
 
-![Build](https://github.com/NHSDigital/eps-FHIR-validator-lambda/workflows/release/badge.svg?branch=main)
+![Build](https://github.com/NHSDigital/eps-FHIR-validator-lambda/actions/workflows/ci.yml/badge.svg?branch=main)   
+Release history can be found ot https://github.com/NHSDigital/eps-FHIR-validator-lambda/releases. Descriptions for the types of changes in a release can be found in the [contributing guidelines](./CONTRIBUTING.md)   
+Deployment history can be found at https://nhsdigital.github.io/eps-FHIR-validator-lambda/
 
 This contains a cloud formation stack which contains a lambda which can be used to validate FHIR R4 messages against implementation guides on [Simplifier](https://simplifier.net/).
 
@@ -200,3 +202,9 @@ These are used to do common commands
 Some pre-commit hooks are installed as part of the install above, to run basic lint checks and ensure you can't accidentally commit invalid changes.
 The pre-commit hook uses python package pre-commit and is configured in the file .pre-commit-config.yaml.
 A combination of these checks are also run in CI.
+
+
+### Github pages
+
+We use github pages to display deployment information. The source for github pages is in the gh-pages branch.   
+As part of the ci and release workflows, the release tag (either the short commit SHA or release tag) is appended to _data/{environment}_releases.csv so we have a history of releases and replaced in _data/{environment}_latest.csv so we now what the latest released version is

RELEASE.md

@@ -0,0 +1,25 @@
+# Release
+
+Managing versioning and releases is done using [semantic-release](https://semantic-release.gitbook.io/semantic-release/). This is a tool that automatically determines the next version number based on the commit history. It also automatically creates a release and publishes it to GitHub and npm.
+
+## Commit messages
+
+Commit messages must follow a commit format inspired by the [esLint conventional commit](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) format. This is enforced with a github workflow on all pull requests. The format is as follows:
+
+```text
+<tag>: [ticket/dependabot] - <description>
+
+Eg:
+Docs: [AEA-1234] - Update README.md
+Upgrade: [dependabot] - Bump pip-licenses from 4.3.3 to 4.3.4
+```
+
+Supported tags and their meanings are defined in the [contributing guidelines](./CONTRIBUTING.md).
+
+## Running a release
+
+Once all desired pull requests have been merged to `main`, a release can be run using the `Release to environments` workflow. This will:
+
+- Run quality checks on the code, including license checks, linting, and unit tests.
+- Run semantic-release to determine the next version number and create a release.
+- Deploy the release to environments.