From e8fb8d1b95ca8f6bfb1ef7e0d6e1b4fc86186b42 Mon Sep 17 00:00:00 2001 From: Thom Carlin Date: Mon, 18 Mar 2024 07:32:47 -0400 Subject: [PATCH] Add commit message guidance --- docs/source/contributing.rst | 19 ++++++++++-- docs/source/developer_guide.rst | 53 +++++++++++++++++++++++++-------- 2 files changed, 57 insertions(+), 15 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index e4fead86f..c301d6cf9 100644 --- a/docs/source/contributing.rst +++ b/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 `_. +============ 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 =============== diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index ff303ec04..210789141 100644 --- a/docs/source/developer_guide.rst +++ b/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 ^^^^