diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..c6104b52 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,9 @@ +# See +# https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners +# https://github.blog/2017-07-06-introducing-code-owners/ + +# Lines starting with '#' are comments. +# Each line is a file pattern followed by one or more owners. + +# These owners will be the default owners for everything in the repo. +* @johnboyes \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..8cbd5c55 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# How to contribute + +Firstly thanks for thinking of contributing - the project is [open source](https://opensource.guide/how-to-contribute/) and all contributions are very welcome :slightly_smiling_face: :boom: :thumbsup: + +[How to report a bug or suggest a new feature](#how-to-report-a-bug-or-suggest-a-new-feature) + +[How to make a contribution](#how-to-make-a-contribution) + +[Local development](#local-development) + * [Visual Studio Code](#visual-studio-code) + * [Codespaces](#codespaces) + * [Local development from scratch](#local-development-from-scratch) + * [Dependencies](#dependencies) + * [Mage](#mage) + +[Running the tests](#running-the-tests) + +## How to report a bug or suggest a new feature + +[Create an issue](https://github.com/agilepathway/label-checker/issues), describing the bug or new feature in as much detail as you can. + +## How to make a contribution + + * [Create an issue](https://github.com/agilepathway/label-checker/issues) describing the change you are proposing. + * [Create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests). The project uses the _[fork and pull model](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models)_: + * [Fork the project](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks) + * Make your changes on your fork + * [Create the pull request for your changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) + * [Update the tests or add new tests](#running-the-tests) to cover the new behaviour. + +## Local development + +### Visual Studio Code + +The easiest way to set up your development environment (unless you have [Codespaces](#codespaces), which is even easier) is to use [Visual Studio Code](https://code.visualstudio.com/)'s [Remote Containers](https://code.visualstudio.com/docs/remote/containers) functionality: + * [System requirements](https://code.visualstudio.com/docs/remote/containers#_system-requirements) + * [Fork the project](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks) + * [Open the local project folder in a container](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container) + * Everything will then be setup for you. You'll be able to run the tests locally. + +### Codespaces + +If you have access to [GitHub Codespaces](https://github.com/features/codespaces/) (which allows full remote +development from withing your browser) then all you need to do is [fork the project](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks) and open it in Codespaces - easy! + +### Local development from scratch + +#### Dependencies + +* [Go](https://golang.org/) +* [Hoverfly](hoverfly.readthedocs.io) (for [running the tests]((#running-the-tests))) + 1. [Download and install Hoverfly](https://docs.hoverfly.io/en/latest/pages/introduction/downloadinstallation.html) + 2. [Download the Hoverfly default cert](https://raw.githubusercontent.com/SpectoLabs/hoverfly/master/core/cert.pem) + 3. [Add and trust the Hoverfly default cert](https://docs.hoverfly.io/en/latest/pages/tutorials/advanced/configuressl/configuressl.html) [(how to add and trust + a cert)](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) + + +#### Mage + +The application is built using [Mage](https://magefile.org/), which is the Go equivalent of [Make](https://www.gnu.org/software/make/). + +## Running the tests + +As [above](#dependencies), you need [Hoverfly](hoverfly.readthedocs.io) to run the tests. + +Run the tests: + +`go test -v .` + +The tests are [table driven](https://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go), which is an important concept to know when amending them. + +The tests also have an integration mode which makes calls to real external services instead of using Hoverfly to virtualise the service calls. When contributing you do not need to run the tests in integration mode (they will not pass unless you are a [maintainer](.github/CODEOWNERS) of the project who has the designated GitHub permissions).