From 695d679893438c6f4d36babd87fa80ded53cde05 Mon Sep 17 00:00:00 2001 From: Anmol Sethi <hi@nhooyr.io> Date: Thu, 22 Aug 2019 02:03:32 -0400 Subject: [PATCH] Improve contributing docs --- docs/CONTRIBUTING.md | 43 ++++++++++++++++++++++++------------------ docs/ISSUE_TEMPLATE.md | 4 ++-- 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 57197ba..a0c9726 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,9 +2,9 @@ ## Issues -Please be as descriptive as possible with your description. +Please be as descriptive as possible. -Reproducible examples are key to fixing bugs and strongly encouraged. +Reproducible examples are key to finding and fixing bugs. ## Pull requests @@ -19,24 +19,31 @@ The commit message title should use the verb tense + phrase that completes the b > This change modifies websocket to \_\_\_\_\_\_\_\_\_ -Be sure to link to an existing issue if one exists. In general, create an issue -before a PR to get some discussion going and to make sure you do not spend time -on a PR that may be rejected. +Be sure to [correctly link](https://help.github.com/en/articles/closing-issues-using-keywords) +to an existing issue if one exists. In general, create an issue before a PR to get some +discussion going and to make sure you do not spend time on a PR that may be rejected. -You can run tests normally with `go test`. -You'll need the [Autobahn Test suite pip package](https://github.com/crossbario/autobahn-testsuite). -In the future this dependency will be removed. See [#117](https://github.com/nhooyr/websocket/issues/117). +CI must pass on your changes for them to be merged. -Please ensure CI passes for your changes. If necessary, you may run CI locally. -The various steps are located in `ci/*.sh`. +### CI -- `ci/fmt.sh` requires node (specifically prettier). -- `ci/lint.sh` requires [shellcheck](https://github.com/koalaman/shellcheck#installing). -- `ci/test.sh` requires the [Autobahn Test suite pip package](https://github.com/crossbario/autobahn-testsuite). -- `ci/run.sh` runs everything in the above order and requires all of their dependencies. +CI will ensure your code is formatted correctly, passes linting and tests. +It will collect coverage and report it to [codecov](https://codecov.io/gh/nhooyr/websocket) +and also upload a `out/coverage.html` artifact that you can click on to interactively +browse coverage. -See [../ci/image/Dockerfile](../ci/image/Dockerfile) for the installation of the CI dependencies on Ubuntu. +You can run CI locally. The various steps are located in `ci/*.sh`. -For CI coverage, you can use either [codecov](https://codecov.io/gh/nhooyr/websocket) or click the -`coverage.html` artifact on the test step in CI. -For coverage details locally, please see `ci/out/coverage.html` after running `ci/run.sh` or `ci/test.sh`. +1. `ci/fmt.sh` requires node (specifically prettier). +1. `ci/lint.sh` requires [shellcheck](https://github.com/koalaman/shellcheck#installing). +1. `ci/test.sh` requires the [Autobahn Test suite pip package](https://github.com/crossbario/autobahn-testsuite). +1. `ci/run.sh` runs the above scripts in order. + +For coverage details locally, please see `ci/out/coverage.html` after running `ci/test.sh`. + +See [ci/image/Dockerfile](ci/image/Dockerfile) for the installation of the CI dependencies on Ubuntu. + +You can also run tests normally with `go test` once you have the +[Autobahn Test suite pip package](https://github.com/crossbario/autobahn-testsuite) +installed. `ci/test.sh` just passes a default set of flags to `go test` to collect coverage, +enable the race detector, run benchmarks and also prettifies the output. diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md index c58db08..939d320 100644 --- a/docs/ISSUE_TEMPLATE.md +++ b/docs/ISSUE_TEMPLATE.md @@ -1,2 +1,2 @@ -<!-- Please read the contributing guidelines. --> -<!-- https://github.com/nhooyr/websocket/blob/master/docs/CONTRIBUTING.md#issues --> +<!-- Please be as descriptive as possible. --> +<!-- Reproducible examples are key to finding and fixing bugs. --> -- GitLab