Merge pull request #69 from contentauth/docs/add-rns-and-reorg

doc: Reorg and add conventional commits guidance

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Before you start, we ask that you understand the following guidelines.
 
 ## Code of conduct
 
-This project adheres to the Adobe [code of conduct](../CODE_OF_CONDUCT.md). By participating,
+This project adheres to the Adobe [code of conduct](CODE_OF_CONDUCT.md). By participating,
 you are expected to uphold this code. Please report unacceptable behavior to
 [Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com).
 
@@ -18,12 +18,10 @@ consensus around project direction and issue solutions within issue threads
 
 ### Current areas of work
 
-The Adobe CAI team has been using this crate as the foundation of Adobe's Content Authenticity Initiative-related products and services since late 2020. As we shift toward making this crate available for open usage, we're aware that there is quite a bit of work to do to create what we'd feel comfortable calling a 1.0 release. We've decided to err on the side of releasing earlier so that people can experiment with it and give us feedback.
-
-We expect to do work on a number of areas in the next few months while we remain in prerelease (0.x) versions. Some broad categories of work (and thus things you might expect to change) are:
+Some broad categories of work (and thus things you might expect to change) are:
 
 * We'll be reviewing and refining our APIs for ease of use and comprehension. We'd appreciate feedback on areas that you find confusing or unnecessarily difficult.
-* We'll also be reviewing our APIs for compliance with Rust community best practices. There are some areas (for example, use of public fields and how we take ownership vs references) where we know some work is required.
+* We'll also be reviewing our APIs for compliance with best practices. 
 * Our documentation is incomplete. We'll be working on refining the documentation.
 * Our testing infrastructure is incomplete. We'll be working on improving test coverage, memory efficiency, and performance benchmarks.
 
@@ -61,11 +59,35 @@ This will give us an opportunity to discuss API design and avoid duplicate effor
 
 ### Pull request titles
 
-The build process automatically adds a pull request (PR) to the [CHANGELOG](CHANGELOG.md) unless the title of the PR begins with `(IGNORE)`. Start PR titles with `(IGNORE)` for minor documentation updates and other trivial fixes that you want to specifically exclude from the CHANGELOG.
+Titles of pull requests that target a long-lived branch such as _main_ or a release-specific branch should follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). This means that the first word of the pull request title should be one of the following:
+
+  * `build`
+  * `chore`
+  * `ci`
+  * `docs`
+  * `feat`
+  * `fix`
+  * `perf`
+  * `refactor`
+  * `revert`
+  * `style`
+  * `test`
+
+Optionally, but preferred, a scope can be added in parentheses after the type. The scope should be the name of the module or component that the commit affects. For example, `feat(api): Introduce a new API to validate 1.0 claims`.
+
+If more detail is warranted, add a blank line and then continue with sentences (these sentences should be punctuated as such) and paragraphs as needed to provide that detail. There is no need to word-wrap this message.
+
+For example:
+
+```text
+feat(api): Introduce a new API to validate 1.0 claims
+
+Repurpose existing v2 API for 0.8 compatibility (read: no validation) mode.
+```
+
+The conventional commit message requirement does not apply to individual commits within a pull request, provided that those commits will be squashed when the PR is merged and the resulting squash commit does follow the conventional commit requirement. This may require the person merging the PR to verify the commit message syntax when performing the squash merge.
 
-Additionally, the build process takes specific actions if the title of a PR begins with certain special strings:
-- `(MINOR)`: Increments the minor version, per [semantic versioning](https://semver.org/) convention. **IMPORTANT:** This flag should be used for any API change that breaks compatibility with previous releases while this crate is in prerelease (version 0.x) status.
-- `(MAJOR)`: Increments the major version number, per [semantic versioning](https://semver.org/) convention.
+TIP: For single-commit PRs, ensure the commit message conforms to the conventional commit requirement, since by default that will also be the title of the PR.
 
 ## From contributor to committer