docs: enhance contributing guidelines (#437)

Problem:

The contributing and developer guidelines in this repository assume a fairly high level of familiarity
with this package's developers workflows and mostly serve as memory jogs for those developers. This
makes it challenging for those who did not create the package to understand the development and contributing
workflows.

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. Also added a pytest marker to the job attachments
cross-account tests just to make it easier to differentiate them from other integration tests.

Signed-off-by: Daniel Neilson <[email protected]>

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,33 +1,64 @@
 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]([email protected]).
+
+  - 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. Output of `deadline --version`: 
+        4. If this is from a version installed by the Deadline Cloud Submitter installer, then what version of the submitter installer?
+
+        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,18 +1,38 @@
+Fixes: *<insert link to GitHub issue here>*
+
 ### What was the problem/requirement? (What/Why)
 
 ### What was the solution? (How)
 
 ### What is the impact of this change?
 
 ### How was this change tested?
-- Have you run `hatch run test` ?
 
-- Have you run `hatch run integ:test` ? See `DEVELOPMENT.md` on "Run integration tests"
+See [DEVELOPMENT.md](https://github.com/aws-deadline/deadline-cloud/blob/mainline/DEVELOPMENT.md#testing) for information on running tests.
+
+- Have you run the unit tests?
+- Have you run the integration tests?
+- Have you made changes to the `download` or `asset_sync` modules? If so, then it is highly recommended
+  that you ensure that the docker-based unit tests pass.
 
 ### Was this change documented?
 
+- Are relevant docstrings in the code base updated?
+- Has the README.md been updated? If you modified CLI arguments, for instance.
+
 ### 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 Contracts](https://github.com/aws-deadline/deadline-cloud/blob/mainline/DEVELOPMENT.md#public-contracts) 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,100 @@ 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
 
-## Contributing via Pull Requests
+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/aws-deadline/deadline-cloud/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.
+
+### Talk with us first
+
+We ask that you please [open a feature request issue](https://github.com/aws-deadline/deadline-cloud/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.
+
+### 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
-[email protected] 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]([email protected]). 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