From d6bdfac0dc0956244a15d8c551e400156464ef6e Mon Sep 17 00:00:00 2001 From: Maja Kurcius Date: Sat, 31 Oct 2020 20:20:13 +0100 Subject: [PATCH] Add CONTRIBUTING.md and development.md (#56) - Add the `CONTRIBUTING.md` document - Add the `docs/development.md` document - Add **Contributing** section to the main `README.md` - Update `docs/README.md`'s table of contents - Delete duplicate issue templates --- .github/ ISSUE_TEMPLATE/bug-report.md | 29 ------- .github/ ISSUE_TEMPLATE/feature-request.md | 14 ---- CONTRIBUTING.md | 46 +++++++++++ README.md | 4 + docs/README.md | 1 + docs/development.md | 88 ++++++++++++++++++++++ 6 files changed, 139 insertions(+), 43 deletions(-) delete mode 100644 .github/ ISSUE_TEMPLATE/bug-report.md delete mode 100644 .github/ ISSUE_TEMPLATE/feature-request.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/development.md diff --git a/.github/ ISSUE_TEMPLATE/bug-report.md b/.github/ ISSUE_TEMPLATE/bug-report.md deleted file mode 100644 index aedf534..0000000 --- a/.github/ ISSUE_TEMPLATE/bug-report.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: Bug report -about: Report a bug in the project ---- - - - -**Description** - - - - - -**Expected result** - - - -**Actual result** - - - -**Steps to reproduce** - - - -**Troubleshooting** - - diff --git a/.github/ ISSUE_TEMPLATE/feature-request.md b/.github/ ISSUE_TEMPLATE/feature-request.md deleted file mode 100644 index 2cc24f3..0000000 --- a/.github/ ISSUE_TEMPLATE/feature-request.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: Feature request -about: Suggest an improvement to the project ---- - - - -**Description** - - - -**Reasons** - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..471301a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +

+ logo + Codeowners Validator - contributing +

+ +🎉🚀🤘 Thanks for your interest in the Codeowners Validator project! 🤘🚀🎉 + +This document contains contribution guidelines for this repository. Read it before you start contributing. + +## Contributing + +Before proposing or adding changes, check the [existing issues](https://github.com/mszostok/codeowners-validator/issues) and make sure the discussion/work has not already been started to avoid duplication. + +If you'd like to see a new feature implemented, use this [feature request template](https://github.com/mszostok/codeowners-validator/issues/new?assignees=&labels=&template=feature_request.md) to create an issue. + +Similarly, if you spot a bug, use this [bug report template](https://github.com/mszostok/codeowners-validator/issues/new?assignees=mszostok&labels=bug&template=bug_report.md) to let us know! + +### Ready for action? Start developing! + +To start contributing, follow these steps: + +1. Fork the `codeowners-validator` repository. + +2. Clone the repository locally. + + > **TIP:** This project uses Go modules, so you can check it out locally wherever you want. It doesn't need to be checked out in `$GOPATH`. + +3. Set the `codeowners-validator` repository as upstream: + + ```bash + git remote add upstream git@github.com:mszostok/codeowners-validator.git + ``` + +4. Fetch all the remote branches for this repository: + + ```bash + git fetch --all + ``` + +5. Set the master branch to point to upstream: + + ```bash + git branch -u upstream/master master + ``` + +You're all set! 🚀 Read the [development](./docs/development.md) document for further instructions. diff --git a/README.md b/README.md index c5122f9..e3a8aa2 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,10 @@ Application exits with different status codes which allow you to easily distingu | **2** | The application was closed because the OS sends a termination signal (SIGINT or SIGTERM). | | **3** | The CODEOWNERS validation failed - executed checks found some issues. | +## Contributing + +Contributions are greatly appreciated! The project follows the typical GitHub pull request model. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. + ## Roadmap The [codeowners-validator roadmap uses Github milestones](https://github.com/mszostok/codeowners-validator/milestone/1) to track the progress of the project. diff --git a/docs/README.md b/docs/README.md index 8e5ccb7..d2aea92 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ Welcome to the Codeowners Validator documentation. ++ [Development](./development.md) + [GitHub Action](./gh-action.md) + [GitHub personal access token](./gh-token.md) + [Release](./release.md) diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..6a8e968 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,88 @@ +[← back to docs](./README.md) + +# Development + +This document contains development instructions. Read it to learn how to develop this project. + +# Table of Contents + + + +- [Prerequisites](#prerequisites) +- [Dependency management](#dependency-management) +- [Testing](#testing) + * [Unit tests](#unit-tests) + * [Lint tests](#lint-tests) + * [Integration tests](#integration-tests) +- [Build a binary](#build-a-binary) + + + +## Prerequisites + +* [Go](https://golang.org/dl/) 1.15 or higher +* [Docker](https://www.docker.com/) +* Make + +Helper scripts may introduce additional dependencies. However, all helper scripts support the `INSTALL_DEPS` environment variable flag. +By default, this flag is set to `false`. This way, the scripts will try to use the tools installed on your local machine. This helps speed up the development process. +If you do not want to install any additional tools, or you want to ensure reproducible script +results, export `INSTALL_DEPS=true`. This way, the proper tool version will be automatically installed and used. + +## Dependency management + +This project uses `go modules` for dependency management. To install all required dependencies, use the following command: + +```bash +go mod download +``` + +## Testing + +### Unit tests + +To run all unit tests, execute: + +```bash +make test-unit +``` + +To generate the unit test coverage HTML report, execute: + +```bash +make test-unit-cover-html +``` + +> **NOTE:** The generated report opens automatically in your default browser. + +### Lint tests + +To check your code for errors, such as typos, wrong formatting, security issues, etc., execute: + +```bash +make test-lint +``` + +To automatically fix detected lint issues, execute: + +```bash +make fix-lint-issues +``` + +### Integration tests + +This project supports the integration tests that are defined in the [tests](../tests) package. The tests are executed against [`gh-codeowners/codeowners-samples`](https://github.com/gh-codeowners/codeowners-samples). + +> **CAUTION:** Currently, running the integration tests both on external PRs and locally by external contributors is not supported, as the teams used for testing are visible only to the organization members. +> At the moment, the `codeowners-validator` repository owner is responsible for running these tests. + +## Build a binary + +To generate a binary for this project, execute: +```bash +make build +``` + +This command generates a binary named `codeowners-validator` in the root directory. + +[↑ Back to top](#table-of-contents)