From df2bbb067c6a61c6d689fd3802b4bc2a5d463dfe Mon Sep 17 00:00:00 2001 From: majakurcius Date: Sat, 31 Oct 2020 19:16:19 +0100 Subject: [PATCH 1/3] Add initial CONTRIBUTING.md --- .github/ ISSUE_TEMPLATE/bug-report.md | 29 ------ .github/ ISSUE_TEMPLATE/feature-request.md | 14 --- CONTRIBUTING.md | 113 +++++++++++++++++++++ 3 files changed, 113 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 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..3c44f9d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +

+ logo + Codeowners Validator - contributing & development +

+ +This document contains contribution guidelines and tips for this repository. Read it to learn how to develop the Codeowners Validator project. + +## Table of Contents + + + + + +## 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. + +## Contributing + +### Issues + +> **NOTE:** Before adding a new issue, check the [existing issues](https://github.com/mszostok/codeowners-validator/issues) to avoid duplicates. + +If you'd like to see a certain feature added to the project, use this [feature request template](./.github/ISSUE_TEMPLATE/feature_request.md) to create an issue. + +Similarly, if you spot a bug, use this [bug report template](./.github/ISSUE_TEMPLATE/bug_report.md) to let us know! + +### PRs + +> **NOTE:** Before proposing changes, check the [existing issues](https://github.com/mszostok/codeowners-validator/issues) and make sure the work has not already been started to avoid duplication. + +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 + ``` + +## 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 [test](./test) 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) \ No newline at end of file From b78b932cab0991b05c6190509ba0f56ee5d1a3de Mon Sep 17 00:00:00 2001 From: majakurcius Date: Sat, 31 Oct 2020 20:04:50 +0100 Subject: [PATCH 2/3] Separate contributing and development docs & add table of contents to the dev. doc --- CONTRIBUTING.md | 97 +++++++-------------------------------------- docs/README.md | 1 + docs/development.md | 86 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+), 82 deletions(-) create mode 100644 docs/development.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c44f9d..b5ebd9d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,113 +1,46 @@

logo - Codeowners Validator - contributing & development + Codeowners Validator - contributing

-This document contains contribution guidelines and tips for this repository. Read it to learn how to develop the Codeowners Validator project. +🎉🚀🤘 Thanks for your interest in the Codeowners Validator project!🤘🚀🎉 -## Table of Contents - - - - - -## 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. +This document contains contribution guidelines for this repository. Read it before you start contributing. ## Contributing -### Issues +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. -> **NOTE:** Before adding a new issue, check the [existing issues](https://github.com/mszostok/codeowners-validator/issues) to avoid duplicates. - -If you'd like to see a certain feature added to the project, use this [feature request template](./.github/ISSUE_TEMPLATE/feature_request.md) to create an issue. +If you'd like to see a new feature implemented, use this [feature request template](./.github/ISSUE_TEMPLATE/feature_request.md) to create an issue. Similarly, if you spot a bug, use this [bug report template](./.github/ISSUE_TEMPLATE/bug_report.md) to let us know! -### PRs - -> **NOTE:** Before proposing changes, check the [existing issues](https://github.com/mszostok/codeowners-validator/issues) and make sure the work has not already been started to avoid duplication. +### 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 ``` -## 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 [test](./test) 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) \ No newline at end of file +You're all set! 🚀 Read the [development](./docs/development.md) document for further instructions. 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..e33d50b --- /dev/null +++ b/docs/development.md @@ -0,0 +1,86 @@ +[← back to docs](./README.md) + +# Development + +This document contains development instructions. Read it to learn how to develop this project. + + + +- [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 [test](./test) 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) From da0b8478d3f39a473e91b5cef4953da751c04163 Mon Sep 17 00:00:00 2001 From: majakurcius Date: Sat, 31 Oct 2020 20:13:37 +0100 Subject: [PATCH 3/3] Apply final fixes --- CONTRIBUTING.md | 8 ++++---- README.md | 4 ++++ docs/development.md | 4 +++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5ebd9d..471301a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ Codeowners Validator - contributing -🎉🚀🤘 Thanks for your interest in the Codeowners Validator project!🤘🚀🎉 +🎉🚀🤘 Thanks for your interest in the Codeowners Validator project! 🤘🚀🎉 This document contains contribution guidelines for this repository. Read it before you start contributing. @@ -11,9 +11,9 @@ This document contains contribution guidelines for this repository. Read it befo 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](./.github/ISSUE_TEMPLATE/feature_request.md) to create an issue. +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](./.github/ISSUE_TEMPLATE/bug_report.md) to let us know! +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! @@ -43,4 +43,4 @@ To start contributing, follow these steps: git branch -u upstream/master master ``` -You're all set! 🚀 Read the [development](./docs/development.md) document for further instructions. +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/development.md b/docs/development.md index e33d50b..6a8e968 100644 --- a/docs/development.md +++ b/docs/development.md @@ -4,6 +4,8 @@ This document contains development instructions. Read it to learn how to develop this project. +# Table of Contents + - [Prerequisites](#prerequisites) @@ -69,7 +71,7 @@ make fix-lint-issues ### Integration tests -This project supports the integration tests that are defined in the [test](./test) package. The tests are executed against [`gh-codeowners/codeowners-samples`](https://github.com/gh-codeowners/codeowners-samples). +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.