From b5b8f7f8fc82203dc8948843d77828e588838769 Mon Sep 17 00:00:00 2001 From: John Boyes Date: Mon, 20 Jul 2020 12:13:11 +0700 Subject: [PATCH] Add contributing guidelines https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors Closes #78 --- .github/CODEOWNERS | 9 +++++ CONTRIBUTING.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 14 ++++++-- 3 files changed, 109 insertions(+), 3 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 CONTRIBUTING.md 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..d34cfe71 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# 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) + * [Tools and technologies](#tools-and-technologies) + * [GitHub Actions](#github-actions) + * [Go](#go) + * [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 + * Write a [good commit message(s)](https://chris.beams.io/posts/git-commit/) for your changes + * [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 within 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](https://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) + + +### Tools and technologies + +#### GitHub Actions + * [General documentation](https://docs.github.com/en/actions) + * The Label Checker is a [Docker container action](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action) + +#### Go + +Some reasons we chose [Go](https://golang.org/): + * [readability](https://yourbasic.org/golang/advantages-over-java-python/#code-transparency) + * [ease of deployment](https://hub.packtpub.com/cloud-native-go-programming/) + * [backwards compatibility](https://yourbasic.org/golang/advantages-over-java-python/#compatibility) + +#### 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](https://hoverfly.readthedocs.io) to run the tests. + +Run the tests: + +`go test -v .` + +The tests are [table driven](https://dave.cheney.net/2019/05/07/prefer-table-driven-tests), 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. You do not need to run the tests in integration mode when contributing (they will not pass unless you are a [maintainer](.github/CODEOWNERS) of the project who has the designated GitHub permissions). diff --git a/README.md b/README.md index 230c7d0d..fca3929e 100644 --- a/README.md +++ b/README.md @@ -116,10 +116,18 @@ You can have as many of the checks configured in the same YAML file as you like. ``` -## Suggestions / bug reports +## Suggestions / bug reports / contributions -[Suggestions and bug reports](https://github.com/agilepathway/label-checker/issues) -are very welcome :slightly_smiling_face: +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](CONTRIBUTING.md#how-to-report-a-bug-or-suggest-a-new-feature) + +* [How to make a contribution](CONTRIBUTING.md#how-to-make-a-contribution) + +* [Local development](CONTRIBUTING.md#local-development) + +* [Running the tests](CONTRIBUTING.md#running-the-tests) + ## Why another label checker?