CONTRIBUTING.md (7509B)
1 # Contributing 2 3 Thank you for your interest in go-toml! We appreciate you considering 4 contributing to go-toml! 5 6 The main goal is the project is to provide an easy-to-use and efficient TOML 7 implementation for Go that gets the job done and gets out of your way – dealing 8 with TOML is probably not the central piece of your project. 9 10 As the single maintainer of go-toml, time is scarce. All help, big or small, is 11 more than welcomed! 12 13 ## Ask questions 14 15 Any question you may have, somebody else might have it too. Always feel free to 16 ask them on the [discussion board][discussions]. We will try to answer them as 17 clearly and quickly as possible, time permitting. 18 19 Asking questions also helps us identify areas where the documentation needs 20 improvement, or new features that weren't envisioned before. Sometimes, a 21 seemingly innocent question leads to the fix of a bug. Don't hesitate and ask 22 away! 23 24 [discussions]: https://github.com/pelletier/go-toml/discussions 25 26 ## Improve the documentation 27 28 The best way to share your knowledge and experience with go-toml is to improve 29 the documentation. Fix a typo, clarify an interface, add an example, anything 30 goes! 31 32 The documentation is present in the [README][readme] and thorough the source 33 code. On release, it gets updated on [pkg.go.dev][pkg.go.dev]. To make a change 34 to the documentation, create a pull request with your proposed changes. For 35 simple changes like that, the easiest way to go is probably the "Fork this 36 project and edit the file" button on Github, displayed at the top right of the 37 file. Unless it's a trivial change (for example a typo), provide a little bit of 38 context in your pull request description or commit message. 39 40 ## Report a bug 41 42 Found a bug! Sorry to hear that :(. Help us and other track them down and fix by 43 reporting it. [File a new bug report][bug-report] on the [issues 44 tracker][issues-tracker]. The template should provide enough guidance on what to 45 include. When in doubt: add more details! By reducing ambiguity and providing 46 more information, it decreases back and forth and saves everyone time. 47 48 ## Code changes 49 50 Want to contribute a patch? Very happy to hear that! 51 52 First, some high-level rules: 53 54 - A short proposal with some POC code is better than a lengthy piece of text 55 with no code. Code speaks louder than words. That being said, bigger changes 56 should probably start with a [discussion][discussions]. 57 - No backward-incompatible patch will be accepted unless discussed. Sometimes 58 it's hard, 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 to 61 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 already 65 included in the PR description. 66 67 It does sound like a lot, but those best practices are here to save time overall 68 and continuously improve the quality of the project, which is something everyone 69 benefits from. 70 71 ### Get started 72 73 The fairly standard code contribution process looks like that: 74 75 1. [Fork the project][fork]. 76 2. Make your changes, commit on any branch you like. 77 3. [Open up a pull request][pull-request] 78 4. Review, potential ask for changes. 79 5. Merge. 80 81 Feel free to ask for help! You can create draft pull requests to gather 82 some early feedback! 83 84 ### Run the tests 85 86 You can run tests for go-toml using Go's test tool: `go test -race ./...`. 87 88 During the pull request process, all tests will be ran on Linux, Windows, and 89 MacOS on the last two versions of Go. 90 91 However, given GitHub's new policy to _not_ run Actions on pull requests until a 92 maintainer clicks on button, it is highly recommended that you run them locally 93 as you make changes. 94 95 ### Check coverage 96 97 We use `go tool cover` to compute test coverage. Most code editors have a way to 98 run and display code coverage, but at the end of the day, we do this: 99 100 ``` 101 go test -covermode=atomic -coverprofile=coverage.out 102 go tool cover -func=coverage.out 103 ``` 104 105 and verify that the overall percentage of tested code does not go down. This is 106 a requirement. As a rule of thumb, all lines of code touched by your changes 107 should be covered. On Unix you can use `./ci.sh coverage -d v2` to check if your 108 code lowers the coverage. 109 110 ### Verify performance 111 112 Go-toml aims to stay efficient. We rely on a set of scenarios executed with Go's 113 builtin benchmark systems. Because of their noisy nature, containers provided by 114 Github Actions cannot be reliably used for benchmarking. As a result, you are 115 responsible for checking that your changes do not incur a performance penalty. 116 You can run their following to execute benchmarks: 117 118 ``` 119 go test ./... -bench=. -count=10 120 ``` 121 122 Benchmark results should be compared against each other with 123 [benchstat][benchstat]. Typical flow looks like this: 124 125 1. On the `v2` branch, run `go test ./... -bench=. -count 10` and save output to 126 a file (for example `old.txt`). 127 2. Make some code changes. 128 3. Run `go test ....` again, and save the output to an other file (for example 129 `new.txt`). 130 4. Run `benchstat old.txt new.txt` to check that time/op does not go up in any 131 test. 132 133 On Unix you can use `./ci.sh benchmark -d v2` to verify how your code impacts 134 performance. 135 136 It is highly encouraged to add the benchstat results to your pull request 137 description. Pull requests that lower performance will receive more scrutiny. 138 139 [benchstat]: https://pkg.go.dev/golang.org/x/perf/cmd/benchstat 140 141 ### Style 142 143 Try to look around and follow the same format and structure as the rest of the 144 code. We enforce using `go fmt` on the whole code base. 145 146 --- 147 148 ## Maintainers-only 149 150 ### Merge pull request 151 152 Checklist: 153 154 - Passing CI. 155 - Does not introduce backward-incompatible changes (unless discussed). 156 - Has relevant doc changes. 157 - Benchstat does not show performance regression. 158 - Pull request is [labeled appropriately][pr-labels]. 159 - Title will be understandable in the changelog. 160 161 1. Merge using "squash and merge". 162 2. Make sure to edit the commit message to keep all the useful information 163 nice and clean. 164 3. Make sure the commit title is clear and contains the PR number (#123). 165 166 ### New release 167 168 1. Decide on the next version number. Use semver. 169 2. Generate release notes using [`gh`][gh]. Example: 170 ``` 171 $ gh api -X POST \ 172 -F tag_name='v2.0.0-beta.5' \ 173 -F target_commitish='v2' \ 174 -F previous_tag_name='v2.0.0-beta.4' \ 175 --jq '.body' \ 176 repos/pelletier/go-toml/releases/generate-notes 177 ``` 178 3. Look for "Other changes". That would indicate a pull request not labeled 179 properly. Tweak labels and pull request titles until changelog looks good for 180 users. 181 4. [Draft new release][new-release]. 182 5. Fill tag and target with the same value used to generate the changelog. 183 6. Set title to the new tag value. 184 7. Paste the generated changelog. 185 8. Check "create discussion", in the "Releases" category. 186 9. Check pre-release if new version is an alpha or beta. 187 188 [issues-tracker]: https://github.com/pelletier/go-toml/issues 189 [bug-report]: https://github.com/pelletier/go-toml/issues/new?template=bug_report.md 190 [pkg.go.dev]: https://pkg.go.dev/github.com/pelletier/go-toml 191 [readme]: ./README.md 192 [fork]: https://help.github.com/articles/fork-a-repo 193 [pull-request]: https://help.github.com/en/articles/creating-a-pull-request 194 [new-release]: https://github.com/pelletier/go-toml/releases/new 195 [gh]: https://github.com/cli/cli 196 [pr-labels]: https://github.com/pelletier/go-toml/blob/v2/.github/release.yml