chore: update CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,60 +1,78 @@
-# Contributing
+# Contributing Guidelines
 
-The project team welcomes contributions from the community. Whether it is a bug report, an enhancement request, or documentation update, we greatly value feedback and contributions from our community.
+Thank you for your interest in contributing to our project. Whether it's a bug
+report, new feature, correction, or additional documentation, we greatly value
+feedback and contributions from our community.
 
-All contributions to this repository must be signed as described on that page. Your signature certifies that you wrote the patch or have the right to pass it on as an open-source patch.
+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.
 
-## Issues
+## Reporting Bugs and Suggesting Enhancements
 
-We welcome you to use the GitHub issues for bug reports, enhancement requests, feature requests, or documentation updates.
+We welcome you to use the [GitHub issues][gh-issues] to report bugs or suggest
+enhancements.
 
-When filing an issue, please check existing open, or recently closed, issues to make sure someone else has not already reported the issue.
+When filing an issue, please check existing open, or recently closed, issues to
+make sure someone else hasn't already reported.
 
-Please try to include as much information as you can. Details like these are incredibly useful:
+Please try to include as much information as you can using the issue form.
+Details like these are incredibly useful:
 
 - A reproducible test case or series of steps.
-- Any modifications you have made relevant to the bug.
+- Any modifications you've made relevant to the bug.
 - Anything unusual about your environment or deployment.
 
-You can also start a discussion on the [discussions][gh-discussions] area to ask questions or share ideas.
+## Contributing via Pull Requests
 
-## Pull Requests
+Contributions using pull requests are appreciated.
 
-Contributions using pull requests are appreciated. Before opening a pull request, please ensure that:
+**Before** sending us a pull request, please ensure that:
 
-1. You check existing open, and recently merged, pull requests to make sure it has not already been addressed for an upcoming release.
-2. You [open a discussion][gh-discussions] to discuss any significant work with the maintainer(s).
-3. You [open an issue][gh-issues] with a clear description of the problem you are trying to solve if one does not already exist.
-4. You are working against the latest source on the `develop` branch.
+1. You [open a discussion][gh-discussions] to discuss any significant work with
+   the maintainer(s).
+2. You [open an issue][gh-issues] and link your pull request to the issue for
+   context.
+3. You are working against the latest source on the `develop` branch.
+4. You check existing open, and recently merged, pull requests to make sure
+   someone else hasn't already addressed the problem.
 
-To submit a pull request, please:
+To open a pull request, please:
 
-1. Fork the repository and clone your fork.
-2. Create a topic branch from the `develop` branch. For example, `feat/add-x` or `fix/update-y`.
-3. Modify the source. Please focus the scope on the specific change you are contributing.
-4. Ensure that the [Pester tests][contributor-testing], if any, pass. Add tests for any new functionality.
-5. Update the documentation, if required. See the `docs` directory for the documentation source.
-6. Commit to your fork [using clear commit messages][git-commit]. Please use [Conventional Commits][conventional-commits].
-7. Submit a pull request, answering any default questions in the pull request, and linking to any related issues for context. See [GitHub flavored markdown syntax][gh-markdown] for references.
-8. Submit a work in progress pull request as a **draft pull request**. Mark the pull request as **ready for review** when you are ready for feedback.
-9. Review any automated checks on the the pull request pass.
-10. Stay engaged in the pull request review process.
+1. Fork the repository.
+2. Modify the source; please focus on the **specific** change you are
+   contributing.
+3. Ensure local tests pass.
+4. Updated the documentation, if required.
+5. Sign-off and commit to your fork
+   [using a clear commit messages][git-commit]. Please use
+   [Conventional Commits][conventional-commits].
+6. Open a pull request, answering any default questions in the pull request.
+7. Pay attention to any automated failures reported in the pull request, and
+   stay involved in the conversation.
 
-GitHub provides additional document on [forking a repository][gh-forks] and [creating a pull request][gh-pulls].
+GitHub provides additional document on [forking a repository][gh-forks] and
+[creating a pull request][gh-pull-requests].
 
-### Contributor Workflow
+### Contributor Flow
 
-This is a general outline of the workflow for contributing to this project:
+This is an outline of the contributor workflow:
 
 - Create a topic branch from where you want to base your work.
 - Make commits of logical units.
-- Make sure your commit messages are [in the proper format][conventional-commits].
-- Push your changes to a topic branch in your fork of the repository.
-- Submit a pull request.
+- Make sure your commit messages are
+  [in the proper format][conventional-commits] **and** are signed-off.
+- Push your changes to the topic branch in your fork.
+- Submit a pull request. If the pull request is a work in progress, please open
+  as draft.
+
+> [!IMPORTANT]
+> This project **requires** that commits are signed-off for the
+> [Developer Certificate of Origin][dco].
 
 Example:
 
-``` shell
+```shell
 git remote add upstream https://github.com/<org-name>/<repo-name>.git
 git checkout --branch feat/add-x develop
 git commit --signoff --message "feat: add support for x
@@ -68,7 +86,8 @@ git push origin feat/add-x
 
 ### Formatting Commit Messages
 
-We follow the conventions on [How to Write a Git Commit Message][git-commit] and [Conventional Commits][conventional-commits].
+We follow the conventions on [How to Write a Git Commit Message][git-commit] and
+[Conventional Commits][conventional-commits].
 
 Be sure to include any related GitHub issue references in the commit message.
 
@@ -84,47 +103,54 @@ Signed-off-by: Jane Doe <[email protected]>
 Ref: #123
 ```
 
-See [GitHub flavored markdown syntax][gh-markdown] for referencing issues, pull requests, and commits.
-
-### Rebasing the Pull Request with Upstream
+### Staying In Sync With Upstream
 
-When your branch gets out of sync with the upstream `develop` branch, use the following to update:
+When your branch gets out of sync with the `vmware/develop` branch, use the
+following to update:
 
-``` shell
+```shell
 git checkout feat/add-x
 git fetch --all
 git pull --rebase upstream develop
 git push --force-with-lease origin feat/add-x
 ```
 
-### Updating a Pull Request
+### Updating Pull Requests
 
-If your pull request fails to pass or needs changes based on code review, you will most likely want to squash these changes into existing commits.
+If your pull request fails to pass or needs changes based on code review, you'll
+most likely want to squash these changes into existing commits.
 
-If your pull request contains a single commit or your changes are related to the most recent commit, you can simply amend the commit.
+If your pull request contains a single commit or your changes are related to the
+most recent commit, you can simply amend the commit.
 
-``` shell
+```shell
 git add .
 git commit --amend
 git push --force-with-lease origin feat/add-x
 ```
 
 If you need to squash changes into an earlier commit, you can use:
 
-``` shell
+```shell
 git add .
 git commit --fixup <commit>
 git rebase --interactive --autosquash develop
 git push --force-with-lease origin feat/add-x
 ```
 
-Be sure to add a comment to the pull request indicating your new changes are ready to review. GitHub does not generate a notification when you `git push`.
+Be sure to add a comment to the pull request indicating your new changes are
+ready to review, as GitHub does not generate a notification when you `git push`.
+
+## Finding Contributions to Work On
+
+Looking at the existing issues is a great way to find something to contribute
+on. If you have an idea you'd like to discuss,
+[open a discussion][gh-discussions].
 
-[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/
-[contributor-testing]: https://vmware.github.io/powershell-module-for-vmware-cloud-foundation-password-management/documentation/testing/
-[git-commit]: http://chris.beams.io/posts/git-commit/
-[gh-discussions]: https://github.com/vmware/powershell-module-for-vmware-cloud-foundation-password-management/discussions
-[gh-forks]: https://help.github.com/articles/fork-a-repo/
-[gh-issues]:https://github.com/vmware/powershell-module-for-vmware-cloud-foundation-password-management/issues
-[gh-markdown]: https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown
-[gh-pulls]: https://help.github.com/articles/creating-a-pull-request/
+[dco]: https://probot.github.io/apps/dco/
+[conventional-commits]: https://conventionalcommits.org
+[gh-discussions]: hhttps://github.com/vmware/powershell-module-for-vmware-cloud-foundation-password-management/discussions
+[gh-forks]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
+[gh-issues]: hhttps://github.com/vmware/powershell-module-for-vmware-cloud-foundation-password-management/issues
+[gh-pull-requests]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+[git-commit]: https://cbea.ms/git-commit