Add commit message guidance

docs/source/contributing.rst

@@ -7,16 +7,29 @@ Receptor is an open source project that lives at https://github.com/ansible/rece
 .. contents::
    :local:
 
+===============
 Code of conduct
-================
+===============
 
 All project contributors must abide by the `Ansible Code of Conduct <https://docs.ansible.com/ansible/latest/community/code_of_conduct.html>`_.
 
+============
 Contributing
-=============
+============
+
+Receptor welcomes community contributions!  See the :ref:`dev_guide` for information about receptor development.
 
-Receptor welcomes community contributions!  See the :ref:`dev_guide` for details.
+-------------
+Pull requests
+-------------
+Contributions to Receptor go through the Github pull request process.
 
+An initial checklist for your change to increase the likelihood of acceptance:
+- No issues when running linters/code checkers
+- No issues from unit/functional tests
+- Write good commit messages. See [How to write a Git commit message](https://cbea.ms/git-commit/).
+
+===============
 Release process
 ===============
 

docs/source/developer_guide.rst

@@ -1,7 +1,8 @@
 .. _dev_guide:
 
+===============
 Developer guide
-================
+===============
 
 Receptor is an open source project that lives at https://github.com/ansible/receptor
 
@@ -10,17 +11,11 @@ Receptor is an open source project that lives at https://github.com/ansible/rece
 
 See the :ref:`contributing:contributing` for more general details.
 
+-------
+Linters
+-------
 
-Testing
---------
-
-Pull requests must pass a suite of integration tests before being merged into ``devel``.
-
-``make test`` will run the full test suite locally. Some of the tests require access to a Kubernetes cluster; these tests will load in the kubeconfig file located at ``$HOME/.kube/config``. One simple way to make these tests work is to start minikube locally before running ``make test``. See https://minikube.sigs.k8s.io/docs/start/ for more information about minikube.
-
-To skip tests that depend on Kubernetes, set environment variable ``export SKIP_KUBE=1``.
-
-Additionally, all code must pass a suite of Go linters. There is a pre-commit yaml file in the receptor repository that points to the linter suite. It is best practice to install the pre-commit yaml so that the linters run locally on each commit.
+All code must pass a suite of Go linters. There is a pre-commit yaml file in the receptor repository that points to the linter suite. It is best practice to install the pre-commit yaml so that the linters run locally on each commit.
 
 .. code::
 
@@ -32,6 +27,21 @@ Additionally, all code must pass a suite of Go linters. There is a pre-commit ya
 
 See https://pre-commit.com/ and https://golangci-lint.run/ for more details on installing and using these tools.
 
+-------
+Testing
+-------
+
+^^^^^^^^^^^
+Development
+^^^^^^^^^^^
+
+Write unit tests for new features or functionality.
+Add/Update tests for bug fixes.
+
+^^^^^^^
+Mocking
+^^^^^^^
+
 We are using gomock to generate mocks for our unit tests. The mocks are living inside of a package under the real implementation, prefixed by ``mock_``. An example is the package mock_workceptor under pkg/workceptor.
 
 In order to genenerate a mock for a particular file, you can run:
@@ -46,13 +56,31 @@ For example, to create/update mocks for Workceptor, we can run:
 
     mockgen -source=pkg/workceptor/workceptor.go -destination=pkg/workceptor/mock_workceptor/workceptor.go
 
+^^^^^^^^^^
+Kubernetes
+^^^^^^^^^^
+
+Some of the tests require access to a Kubernetes cluster; these tests will load in the kubeconfig file located at ``$HOME/.kube/config``. One simple way to make these tests work is to start minikube locally before running ``make test``. See https://minikube.sigs.k8s.io/docs/start/ for more information about minikube.
+
+To skip tests that depend on Kubernetes, set environment variable ``export SKIP_KUBE=1``.
+
+^^^^^^^^^
+Execution
+^^^^^^^^^
+
+Pull requests must pass a suite of unit and integration tests before being merged into ``devel``.
+
+``make test`` will run the full test suite locally.
+
+-----------
 Source code
 -----------
 
 The next couple of sections are aimed to orient developers to the receptor codebase and provide a starting point for understanding how receptor works.
 
+^^^^^^^^^^^^^^^^^^^^^
 Parsing receptor.conf
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 
 Let's see how items in the config file are mapped to Golang internals.
 
@@ -133,6 +161,7 @@ This gets a new TCP dialer object and passes it to the netceptor AddBackend meth
 
 In general, when studying how the start up process works in receptor, take a look at the Init, Prepare, and Run methods throughout the code, as these are the entry points to running those specific components of receptor.
 
+^^^^
 Ping
 ^^^^