docs: enhance contributing guidelines to be more accessible (#143)

Problem:

The contributing and development guidelines in this repository could benefit from
an improvement pass to make workflows, expectations, and intentions clearer.

Solution:

Rework/refactor the CONTRIBUTING.md, DEVELOPMENT.md, GitHub issue templates, and pull
request template with the goal of improving understandability to those not familiar with
the code base, hatch-based workflows, GitHub pull request workflows, and our use of
conventional commits

Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,33 +1,63 @@
 name: "\U0001F41B Bug Report"
 description: Report a bug
-title: "Bug: TITLE"
-labels: ["bug"]
+title: "Bug: (short bug description)"
+labels: ["bug", "needs triage"]
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to fill out this bug report!
+
+        ⚠️ If the bug that you are reporting is a security-related issue or security vulnerability,
+        then please do not create a report via this template. Instead please 
+        notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/)
+        or directly via email to [AWS Security](aws-security@amazon.com).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: What is the problem? A clear and concise description of the bug.
+    validations:
+      required: true
+
   - type: textarea
     id: expected_behaviour
     attributes:
       label: Expected Behaviour
+      description: What did you expect to happen?
     validations:
       required: true
 
   - type: textarea
     id: current_behaviour
     attributes:
       label: Current Behaviour
+      description: What actually happened? Please include as much detail as you can.
     validations:
       required: true
 
   - type: textarea
     id: reproduction_steps
     attributes:
       label: Reproduction Steps
+      description: |
+        Please provide as much detail as you can to help us understand how we can reproduce the bug.
+        Step by step instructions and self-contained code snippets are ideal.
     validations:
       required: true
 
   - type: textarea
-    id: code_snippet
+    id: environment
     attributes:
-      label: Code Snippet
+      label: Environment
+      description: Please provide information on the environment and software versions that you are using to reproduce the bug.
+      value: |
+        At minimum:
+        1. Operating system: (e.g. Windows Server 2022; Amazon Linux 2023; etc.) 
+        2. Output of `python3 --version`: 
+        3. Version of this library.
+
+        Please share other details about your environment that you think might be relevant to reproducing the bug.
     validations:
       required: true
-

.github/ISSUE_TEMPLATE/doc.yml

@@ -1,8 +1,8 @@
 
 name: "📕 Documentation Issue"
 description: Issue in the documentation
-title: "Docs: TITLE"
-labels: ["documenation"]
+title: "Docs: (short description of the issue)"
+labels: ["documenation", "needs triage"]
 body:
   - type: textarea
     id: documentation_issue

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,17 +1,37 @@
 name: "\U0001F680 Feature Request"
 description: Request a new feature
-title: "Feature request: TITLE"
-labels: ["feature"]
+title: "Feature request: (short description of the feature)"
+labels: ["feature", "needs triage"]
 body:
   - type: textarea
-    id: use_case
+    id: problem
     attributes:
-      label: Use Case
+      label: Describe the problem
+      description: |
+        Help us understand the problem that you are trying to solve, and why it is important to you.
+        Provide as much detail as you are able.
     validations:
       required: true
+
   - type: textarea
     id: proposed_solution
     attributes:
       label: Proposed Solution
+      description: |
+        Describe your proposed feature that you see solving this problem for you. If you have a
+        full or partial prototype implementation then please open a draft pull request and link to
+        it here as well.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Example Use Cases
+      description: |
+        Provide some sample code snippets or shell scripts that show how **you** would use this feature as
+        you have proposed it.
     validations:
       required: true
+
+

.github/ISSUE_TEMPLATE/maintenance.yml

@@ -1,17 +1,19 @@
 name: "🛠️ Maintenance"
 description: Some type of improvement
-title: "Maintenance: TITLE"
-labels: ["feature"]
+title: "Maintenance: (short description of the issue)"
+labels: ["feature", "needs triage"]
 body:
   - type: textarea
     id: description
     attributes:
       label: Description
+      description: Describe the improvement and why it is important to do.
     validations:
       required: true
   - type: textarea
     id: solution
     attributes:
       label: Solution
+      description: Provide any ideas you have for how the suggestion can be implemented.
     validations:
       required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,5 @@
+Fixes: *<insert link to GitHub issue here>*
+
 ### What was the problem/requirement? (What/Why)
 
 ### What was the solution? (How)
@@ -6,10 +8,27 @@
 
 ### How was this change tested?
 
+See [DEVELOPMENT.md](https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/blob/mainline/DEVELOPMENT.md#testing) for information on running tests.
+
+- Have you run the unit tests?
+
 ### Was this change documented?
 
+- Are relevant docstrings in the code base updated?
+
 ### Is this a breaking change?
 
+A breaking change is one that modifies a public contract in a way that is not backwards compatible. See the
+[Public Interfaces](https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/blob/mainline/DEVELOPMENT.md#the-packages-public-interface) section
+of the DEVELOPMENT.md for more information on the public contracts.
+
+If so, then please describe the changes that users of this package must make to update their scripts, or Python applications.
+
+### Does this change impact security?
+
+- Does the change need to be threat modeled? For example, does it create or modify files/directories that must only be readable by the process owner?
+    - If so, then please label this pull request with the "security" label. We'll work with you to analyze the threats.
+
 ----
 
 *By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.*

CONTRIBUTING.md

@@ -6,62 +6,106 @@ documentation, we greatly value feedback and contributions from our community.
 Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
 information to effectively respond to your bug report or contribution.
 
+Table of contents:
+
+* [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests)
+* [Development](#development)
+    * [Finding contributions to work on](#finding-contributions-to-work-on)
+    * [Talk with us first](#talk-with-us-first)
+    * [Contributing via Pull Requests](#contributing-via-pull-requests)
+    * [Conventional Commits](#conventional-commits)
+* [Licensing](#licensing)
+
 ## Reporting Bugs/Feature Requests
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
 
 When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
-reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
-
-* A reproducible test case or series of steps
-* The version of our code being used
-* Any modifications you've made relevant to the bug
-* Anything unusual about your environment or deployment
+reported the issue. Please try to include as much information as you can.
 
 ## Development
 
-Please see [DEVELOPMENT.md](./DEVELOPMENT.md) for more information.
+We welcome you to contribute features and bug fixes via a [pull request](https://help.github.com/articles/creating-a-pull-request/).
+If you are new to contributing to GitHub repositories, then you may find the 
+[GitHub documentation on collaborating with the fork and pull model](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model)
+informative; this is the model that we follow.
+
+Please see [DEVELOPMENT.md](./DEVELOPMENT.md) for information about how to navigate this package's
+code base and development practices.
+
+### Finding contributions to work on
+
+If you are not sure what you would like to contribute, then looking at the existing issues is a great way to find
+something to contribute on. Looking at 
+[issues that have the "help wanted" or "good first issue" labels](https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22)
+are a good place to start, but please dive into any issue that interests you whether it has those labels or not.
 
-## Contributing via Pull Requests
+### Talk with us first
+
+We ask that you please [open a feature request issue](https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/issues/new/choose)
+(if one does not already exist) and talk with us before posting a pull request that contains a significant amount of work,
+or one that proposes a change to a public interface such as to the interface of a publicly exported Python function or to
+the command-line interfaces' commands or arguments. We want to make sure that your time and effort is respected by working
+with you to design the change before you spend much of your time on it. If you want to create a draft pull request to show what
+you are thinking and then talk with us, then that works with us as well.
+
+We prefer that this package contain primarily features that are useful to many users of it, rather than features that are specific
+to niche workflows. If you have a feature in mind, but are not sure whether it is niche or not then please 
+[open a feature request issue](https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/issues/new/choose). We will do our best to help
+you make that assessment, and posting a public issue will help others find your feature idea and add their support if they
+would also find it useful.
+
+### Contributing via Pull Requests
 
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
-1. You are working against the latest source on the *main* branch.
+1. You are working against the latest source on the *mainline* branch.
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
+4. Your pull request will be focused on a single change - it is easier for us to understand when a change is focused rather
+   than changing multiple things at once.
 
 To send us a pull request, please:
 
 1. Fork the repository.
-2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
-3. Ensure local tests pass.
-4. Commit to your fork using clear commit messages.
+2. Modify the source and add tests for your change; please focus on the specific change you are contributing.
+   If you also reformat all the code, it will be hard for us to focus on your change.
+   Please see [DEVELOPMENT.md](./DEVELOPMENT.md) for tips.
+3. Ensure tests pass. Please see the [Testing](./DEVELOPMENT.md#testing) section for information on tests.
+4. Commit to your fork using clear commit messages. Note that all AWS Deadline Cloud GitHub repositories require the use
+   of [conventional commit](#conventional-commits) syntax for the title of your commit.
 5. Send us a pull request, answering any default questions in the pull request interface.
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
 GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
-## Finding contributions to work on
-
-Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
-
+### Conventional commits
 
-## Code of Conduct
+The commits in this repository are all required to use [conventional commit syntax](https://www.conventionalcommits.org/en/v1.0.0/)
+in their title to help us identify the kind of change that is being made, automatically generate the changelog, and 
+automatically identify next release version number. Only the first commit that deviates from mainline in your pull request
+must adhere to this requirement.
 
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-opensource-codeofconduct@amazon.com with any additional questions or comments.
+We ask that you use these commit types in your commit titles:
 
+* `feat` - When the pull request adds a new feature or functionality;
+* `fix` - When the pull request is implementing a fix to a bug;
+* `test` - When the pull request is only implementing an addition or change to tests or the testing infrastructure;
+* `docs` - When the pull request is primarily implementing an addition or change to the package's documentation;
+* `refactor` - When the pull request is implementing only a refactor of existing code;
+* `ci` - When the pull request is implementing a change to the CI infrastructure of the packge;
+* `chore` - When the pull request is a generic maintenance task.
 
-## Security issue notifications
+We also require that the type in your conventional commit title end in an exclaimation point (e.g. `feat!` or `fix!`)
+if the pull request should be considered to be a breaking change in some way. Please also include a "BREAKING CHANGE" footer
+in the description of your commit in this case ([example](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-both--and-breaking-change-footer)).
+Examples of breaking changes include any that implements a backwards-imcompatible change to a public Python interface,
+the command-line interface, or the like. 
 
-We take all security reports seriously. When we receive such reports, we will 
-investigate and subsequently address any potential vulnerabilities as quickly 
-as possible. If you discover a potential security issue in this project, please 
-notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/)
-or directly via email to [AWS Security](aws-security@amazon.com). Please do not 
-create a public GitHub issue in this project.
+If you need change a commit message, then please see the
+[GitHub documentation on the topic](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message)
+to guide you.
 
 ## Licensing