From 8611afa3f0b6867454962e63a31a37cff0604dda Mon Sep 17 00:00:00 2001
From: Blake Ridgway <blake@blakeridgway.dev>
Date: Wed, 11 Jun 2025 20:54:43 -0500
Subject: [PATCH] docs: add commit message guidelines

Establish a formal convention for Git commit messages to improve the
clarity and readability of the project's history.

This standard follows the Conventional Commits specification and will
enable potential future automation for changelog generation.
---
 CONTRIBUTING.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dc0a87c..cda63e3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,9 +42,97 @@ are expected to uphold this code. Please report unacceptable behavior to
     applicable.
 4.  Add or update tests to ensure your changes are covered.
 5.  Ensure all tests pass locally before pushing.
-6.  Commit your changes with a descriptive commit message.
+6.  Commit your changes using our commit message guidelines (see below).
 7.  Push to the branch: `git push origin feature/AmazingFeature`.
 8.  Open a Merge Request to the `main` branch of the original repository.
 9.  A project maintainer will review your Merge Request.
 
+### Commit Message Guidelines
+
+We follow a convention for our commit messages that helps us maintain a clear
+and automated project history. Please follow this format for your commits.
+
+Each commit message consists of a **header**, an optional **body**, and an
+optional **footer**.
+
+```
+<type>: <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+---
+
+#### **Header**
+
+The header is mandatory and should be a single line that contains a succinct
+description of the change.
+
+`<type>: <subject>`
+
+**Allowed `type` values:**
+
+-   **feat**: A new feature
+-   **fix**: A bug fix
+-   **docs**: Changes to documentation only
+-   **style**: Style/format changes (whitespace, semi-colons, etc.)
+-   **refactor**: A code change that neither fixes a bug nor adds a feature
+-   **perf**: A code change that improves performance
+-   **test**: Adding missing tests or correcting existing tests
+-   **build**: Changes that affect the build system or external dependencies
+-   **ci**: Changes to our CI configuration files and scripts
+
+**Subject:**
+
+The subject contains a short description of the change.
+-   Use the imperative, present tense: "change" not "changed" nor "changes".
+-   Don't capitalize the first letter.
+-   No dot (.) at the end.
+
+---
+
+#### **Body** (Optional)
+
+The body should provide more detail about the changes. Use it to explain the
+motivation behind the change and contrast it with previous behavior.
+
+---
+
+#### **Footer** (Optional)
+
+The footer is used to reference tracking IDs like GitLab Issues or Merge
+Requests.
+
+-   Example: `Resolves #207`
+-   Example: `See merge request !15`
+
+---
+
+#### **Examples**
+
+**A simple fix:**
+```
+fix: correct validation for user email format
+```
+
+**A new feature with a body and footer:**
+```
+feat: add user password reset API endpoint
+
+Implement the /api/users/reset-password endpoint. This includes
+generating a secure, single-use token and sending an email to the
+user with the reset link.
+
+Resolves #88
+```
+
+**A change to the CI pipeline:**
+```
+ci: add linting stage to build pipeline
+```
+
+---
+
 Thank you for your contribution!
\ No newline at end of file