flesh out commit messages spec

structured commit message standard based on conventional commits

docs/verso-standards/commit-messages.md

@@ -25,3 +25,86 @@ Here is "what not to do" when writing commit messages:
 - `Updated README with DOI`: This tells you what file was changed and what was added; since READMEs are not code, it typically doesn't need a why. It is also short and to the point.
 - `Created new API endpoint in <file> to support <feature>`; Tells us what (created api endpoint), where (in \<file\>), and why (support a new \<feature\>)
 - `Added new data files for <thing>`: An example of what to do if you're just uploading data that should be tracked in Git; ie geojson, certain csv formatted data. Also tells us what the data files are for.
+
+## Structured Commit Messages
+
+As mentioned above, select projects may have a stricter format for commit messages on the `main`/default branch. This makes it possible to run automations based on commit activity; ie, generating changelogs or cutting releases. This is based on Conventional Commits.
+
+### Basic Format
+
+```
+<type>: <subject>
+
+<optional body>
+
+<optional footer>
+```
+
+**type** is required can be any one of:
+
+- `fix`: Fixes a bug
+- `feat`: New feature or functionality
+- `docs`: Improves or alters documentation
+- `chore`: Formatting stuff, non-breaking-change updates
+
+Types are _always_ lowercase.
+
+Additionally, if a `feat`/`fix` contains a [breaking change](#breaking-change) it can be suffixed with a bang (`!`) like this: `feat!: <subject>`
+
+`<subject>` is the short description that is [described above](#good-messages). It is always required.
+
+`<optional body>` is a section defined by a separation of _two newlines_ and can be used if more context may be necessary. Typically, it is present in the automated commits created by things like pull request merge commits. You don't usually need to write this yourself.
+
+`<optional footer>` can be used to note things like related issues, who reviewed something, etc. This is not something a dev needs to think about on a day-to-day basis. [More info](#footers)
+
+Any given line must not be longer than 80-100 characters! Use linebreaks/newlines when necessary; with the exception that if your subject needs a linebreak, it's probably too long.
+
+### More Format Options
+
+#### Scopes
+
+Scopes are sometimes helpful to note that that a given commit only affects a certain part of the project. A good example is if you have a mobile app, web app, and backend API in the same repository; you can use scopes like `web`, `mobile`, and `api`/`backend`.
+
+```
+fix(web): ensure breakpoints are used properly
+
+feat(api): new endpoint to find get users' friends
+fix(backend)!: fix bug that clients were depending on
+
+docs(mobile): add comments to clarify business logic
+```
+
+#### Footers
+
+Footers can be used to add certain details:
+
+```
+Reviewed by: Charlie Catamount <ccatamou@uvm.edu>
+Closes: #1791, #1928
+```
+
+See full in-context example below.
+
+### Full Example
+
+```
+feat(api): new endpoint to find get users' friends
+
+This endpoint will be used by the new Friends feature in the mobile app.
+
+Reviewed by: Charlie Catamount <ccatamou@uvm.edu>
+Closes: #1791, #1928
+```
+
+### Differences from Conventional Commits
+
+This standard is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard but departs from it in few key ways in order to simplify things.
+
+- **Types:** This standard limits the number of types and expandes the scope of what they can be used for.
+- **BREAKING CHANGE**: We do not use `BREAKING CHANGE`
+
+## Terms
+
+#### Breaking Change
+
+> A breaking change is any change which modifies the public interface to a module in such a way that causes any consuming modules to fail either at compile-time or run-time. In other words, any change which requires consuming code to change in order to maintain the same behavior.