1## Contributing 2 3Thank you for your interest in go-toml! We appreciate you considering 4contributing to go-toml! 5 6The main goal is the project is to provide an easy-to-use TOML 7implementation for Go that gets the job done and gets out of your way – 8dealing with TOML is probably not the central piece of your project. 9 10As the single maintainer of go-toml, time is scarce. All help, big or 11small, is more than welcomed! 12 13### Ask questions 14 15Any question you may have, somebody else might have it too. Always feel 16free to ask them on the [issues tracker][issues-tracker]. We will try to 17answer them as clearly and quickly as possible, time permitting. 18 19Asking questions also helps us identify areas where the documentation needs 20improvement, or new features that weren't envisioned before. Sometimes, a 21seemingly innocent question leads to the fix of a bug. Don't hesitate and 22ask away! 23 24### Improve the documentation 25 26The best way to share your knowledge and experience with go-toml is to 27improve the documentation. Fix a typo, clarify an interface, add an 28example, anything goes! 29 30The documentation is present in the [README][readme] and thorough the 31source code. On release, it gets updated on [GoDoc][godoc]. To make a 32change to the documentation, create a pull request with your proposed 33changes. For simple changes like that, the easiest way to go is probably 34the "Fork this project and edit the file" button on Github, displayed at 35the top right of the file. Unless it's a trivial change (for example a 36typo), provide a little bit of context in your pull request description or 37commit message. 38 39### Report a bug 40 41Found a bug! Sorry to hear that :(. Help us and other track them down and 42fix by reporting it. [File a new bug report][bug-report] on the [issues 43tracker][issues-tracker]. The template should provide enough guidance on 44what to include. When in doubt: add more details! By reducing ambiguity and 45providing more information, it decreases back and forth and saves everyone 46time. 47 48### Code changes 49 50Want to contribute a patch? Very happy to hear that! 51 52First, some high-level rules: 53 54* A short proposal with some POC code is better than a lengthy piece of 55 text with no code. Code speaks louder than words. 56* No backward-incompatible patch will be accepted unless discussed. 57 Sometimes it's hard, and Go's lack of versioning by default does not 58 help, but we try not to break people's programs unless we absolutely have 59 to. 60* If you are writing a new feature or extending an existing one, make sure 61 to write some documentation. 62* Bug fixes need to be accompanied with regression tests. 63* New code needs to be tested. 64* Your commit messages need to explain why the change is needed, even if 65 already included in the PR description. 66 67It does sound like a lot, but those best practices are here to save time 68overall and continuously improve the quality of the project, which is 69something everyone benefits from. 70 71#### Get started 72 73The fairly standard code contribution process looks like that: 74 751. [Fork the project][fork]. 762. Make your changes, commit on any branch you like. 773. [Open up a pull request][pull-request] 784. Review, potential ask for changes. 795. Merge. You're in! 80 81Feel free to ask for help! You can create draft pull requests to gather 82some early feedback! 83 84#### Run the tests 85 86You can run tests for go-toml using Go's test tool: `go test ./...`. 87When creating a pull requests, all tests will be ran on Linux on a few Go 88versions (Travis CI), and on Windows using the latest Go version 89(AppVeyor). 90 91#### Style 92 93Try to look around and follow the same format and structure as the rest of 94the code. We enforce using `go fmt` on the whole code base. 95 96--- 97 98### Maintainers-only 99 100#### Merge pull request 101 102Checklist: 103 104* Passing CI. 105* Does not introduce backward-incompatible changes (unless discussed). 106* Has relevant doc changes. 107* Has relevant unit tests. 108 1091. Merge using "squash and merge". 1102. Make sure to edit the commit message to keep all the useful information 111 nice and clean. 1123. Make sure the commit title is clear and contains the PR number (#123). 113 114#### New release 115 1161. Go to [releases][releases]. Click on "X commits to master since this 117 release". 1182. Make note of all the changes. Look for backward incompatible changes, 119 new features, and bug fixes. 1203. Pick the new version using the above and semver. 1214. Create a [new release][new-release]. 1225. Follow the same format as [1.1.0][release-110]. 123 124[issues-tracker]: https://github.com/pelletier/go-toml/issues 125[bug-report]: https://github.com/pelletier/go-toml/issues/new?template=bug_report.md 126[godoc]: https://godoc.org/github.com/pelletier/go-toml 127[readme]: ./README.md 128[fork]: https://help.github.com/articles/fork-a-repo 129[pull-request]: https://help.github.com/en/articles/creating-a-pull-request 130[releases]: https://github.com/pelletier/go-toml/releases 131[new-release]: https://github.com/pelletier/go-toml/releases/new 132[release-110]: https://github.com/pelletier/go-toml/releases/tag/v1.1.0 133