diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 000000000..d169cf8d2 --- /dev/null +++ b/HACKING.md @@ -0,0 +1,141 @@ +# Hacking guidelines + +## Developer dependencies + +To develop httpexpect, you need: + +* [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) + +* [stringer](https://github.com/golang/tools) + + `go install golang.org/x/tools/cmd/stringer@latest` + +## Makefile targets + +Re-generate, build, lint, and test everything: + +``` +make +``` + +Run tests: + +``` +make test +``` + +Run only short tests: + +``` +make short +``` + +Run gofmt: + +``` +make fmt +``` + +Run go generate: + +``` +make gen +``` + +Run go mod tidy: + +``` +make tidy +``` + +## Comment formatting + +Exported functions should have documentation comments, formatted as follows: + +* short function description, indented with one SPACE +* empty line +* optional details, indented with one SPACE +* empty line +* `Example:` line, indented with one SPACE +* empty line +* example code, indented with one TAB +* no more empty lines + +**GOOD:** + +```go +// Short function description. +// +// Optional details, probably multiple +// lines or paragraphs. +// +// Example: +// +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** no space after `//`: + +```go +//Short function description. +// +// Example: +// +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** missing empty line before `Example:` + +```go +// Short function description. +// Example: +// +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** missing empty line after `Example:` + +```go +// Short function description. +// +// Example: +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** forgetting to indent example code: + +```go +// Short function description. +// +// Example: +// +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** using spaces instead of TAB to indent example code: + +```go +// Short function description. +// +// Example: +// +// exampleCode() +func MyFunction() { ... } +``` + +**BAD:** extra empty line between comment and function: + +```go +// Short function description. +// +// Example: +// +// exampleCode() + +func MyFunction() { ... } +``` diff --git a/README.md b/README.md index d98bf9e30..d1349fe50 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,14 @@ Community forum and Q&A board is right on GitHub in [discussions tab](https://gi For more interactive discussion, you can join [discord chat](https://discord.gg/5SCPCuCWA9). +## Contributing + +Feel free to report bugs, suggest improvements, and send pull requests! Please add documentation and tests for new features. + +This project highly depends on contributors. Thank you all for your amazing work! + +If you would like to submit code, see [HACKING.md](HACKING.md). + ## Examples See [`_examples`](_examples) directory for complete standalone examples. @@ -832,54 +840,6 @@ e := httpexpect.WithConfig(httpexpect.Config{ * [`http-test`](https://github.com/vsco/http-test) * [`go-json-rest`](https://github.com/ant0ine/go-json-rest) -## Contributing - -Feel free to report bugs, suggest improvements, and send pull requests! Please add documentation and tests for new features. - -Install developer dependencies: - -* [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) - -* [stringer](https://github.com/golang/tools) - - `go install golang.org/x/tools/cmd/stringer@latest` - -Re-generate, build, lint, and test everything: - -``` -make -``` - -Run tests: - -``` -make test -``` - -Run only short tests: - -``` -make short -``` - -Run gofmt: - -``` -make fmt -``` - -Run go generate: - -``` -make gen -``` - -Run go mod tidy: - -``` -make tidy -``` - ## License [MIT](LICENSE)