# Contributing to pigeon

There are various ways to help support this open source project:

* if you use pigeon and find it useful, talk about it - that's probably the most basic way to help any open-source project: getting the word out that it exists and that it can be useful
* if you use pigeon and find bugs, please [file an issue][0]
* if something is poorly documented, or doesn't work as documented, this is also a bug, please [file an issue][0]
* if you can fix the issue (whether it is documentation- or code-related), then [submit a pull-request][1] - but read on to see what should be done to get it merged
* if you would like to see some new feature/behaviour being implemented, please first [open an issue][0] to discuss it because features are less likely to get merged compared to bug fixes

## Submitting a pull request

Assuming you already have a copy of the repository (either via `go get`, a github fork, a clone, etc.), you will also need `make` to regenerate all tools and files generated when a dependency changes. I use GNU make version 4.1, other versions of make may work too but haven't been tested.

Run `make` in the root directory of the repository. That will create the bootstrap builder, the bootstrap parser, and the final parser, along with some generated Go files. Once `make` is run successfully, run `go test ./...` in the root directory to make sure all tests pass.

Once this is done and tests pass, you can start implementing the bug fix (or the new feature provided **it has already been discussed and agreed in a github issue** first).

For a bug fix, the best way to proceed is to first write a test that proves the bug, then write the code that fixes the bug and makes the test pass. All other tests should still pass too (unless it relied on the buggy behaviour, in which case existing tests must be fixed).

For a new feature, it must be thoroughly tested. New code without new test(s) is unlikely to get merged.

Respect the coding style of the repository, which means essentially to respect the [coding guidelines of the Go community][2]. Use `gofmt` to format your code, and `goimports` to add and format the list of imported packages (or do it manually, but in a `goimports`-style).

Once all code is done and tests pass, regenerate the whole tree with `make`, run `make lint` (does need [`golangci-lint`](https://golangci-lint.run/))to make sure the code is correct, and run tests again. You are now ready to submit the pull request.

## Licensing

All pull requests that get merged will be made available under the BSD 3-Clause license (see the LICENSE file for details), as the rest of the pigeon repository. Do not submit pull requests if you do not want your contributions to be made available under those terms.

[0]: https://github.com/mna/pigeon/issues/new
[1]: https://github.com/mna/pigeon/pulls
[2]: https://github.com/golang/go/wiki/CodeReviewComments
