From 54ca7602bb82cb639e80b09ce851ebb0625a7ed3 Mon Sep 17 00:00:00 2001
From: Craig Sawyer <craig-sawyer@hotmail.co.uk>
Date: Wed, 15 May 2024 15:30:32 +0100
Subject: [PATCH] docs: added semantic release user guide

---
 docs/user-guide.md                   | 16 ++++++++++++
 docs/user-guides/Semantic_release.md | 38 ++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/user-guide.md
 create mode 100644 docs/user-guides/Semantic_release.md

diff --git a/docs/user-guide.md b/docs/user-guide.md
new file mode 100644
index 00000000..c133ff02
--- /dev/null
+++ b/docs/user-guide.md
@@ -0,0 +1,16 @@
+@ -0,0 +1,15 @@
+# User Guides
+
+- [Perform static analysis](./user-guides/Perform_static_analysis.md)
+- [Run Git hook on commit](./user-guides/Run_Git_hooks_on_commit.md)
+- [Scan dependencies](./user-guides/Scan_dependencies.md)
+- [Scan secrets](./user-guides/Scan_secrets.md)
+- [Semantic release](./user-guides/Semantic_release.md)
+- [Sign Git commits](./user-guides/Sign_Git_commits.md)
+- [Test GitHub Actions locally](./user-guides/Test_GitHub_Actions_locally.md)
+
+## Developer Guides
+
+- [Bash and Make](./developer-guides/Bash_and_Make.md)
+- [Scripting Docker](./developer-guides/Scripting_Docker.md)
+- [Scripting Terraform](./developer-guides/Scripting_Terraform.md)
diff --git a/docs/user-guides/Semantic_release.md b/docs/user-guides/Semantic_release.md
new file mode 100644
index 00000000..c1d45508
--- /dev/null
+++ b/docs/user-guides/Semantic_release.md
@@ -0,0 +1,38 @@
+# Guide: Semantic release
+
+- [Guide: Semantic release](#guide-semantic-release)
+  - [Overview](#overview)
+  - [Key files](#key-files)
+  - [Configuration checklist](#configuration-checklist)
+  - [Testing](#testing)
+
+## Overview
+
+Semantic release ([semantic-release](https://semantic-release.gitbook.io/semantic-release)) is used for automatically tagging and creating GitHub releases with change logs from commit messages. It uses the [SemVer](https://semver.org/) convention and the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification by describing the features, fixes, and breaking changes made in commit messages.
+
+The table below shows which commit message gets you which release type when semantic-release runs (using the default configuration):
+
+| Commit message | Release type |
+|----------------|--------------|
+| `fix(pencil): stop graphite breaking when too much pressure applied` | ~~Patch~~ Fix Release |
+| `feat(pencil): add 'graphiteWidth' option` | ~~Minor~~ Feature Release |
+| `perf(pencil): remove graphiteWidth option`<br/>`BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release <br/>(Note that the BREAKING CHANGE:  token must be in the footer of the commit) |
+
+## Key files
+
+- [`.releaserc`](../../.releaserc): semantic-release's configuration file, written in YAML or JSON
+
+## Configuration checklist
+
+Configuration should be made in the `.releaserc` file.
+
+- Adjust the [configuration settings](https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches) to align with your project's branching strategy
+- Configure [plugins](https://semantic-release.gitbook.io/semantic-release/usage/plugins) depending on your needs
+
+## Testing
+
+```shell
+$ make runner-act workflow="cicd-1-pull-request" job="semantic-release"
+```
+
+This will `dry-run` a semantic release and output the variables to the console