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 and efficient TOML
7implementation for Go that gets the job done and gets out of your way – dealing
8with 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 small, is
11more than welcomed!
12
13## Ask questions
14
15Any question you may have, somebody else might have it too. Always feel free to
16ask them on the [discussion board][discussions]. We will try to answer them as
17clearly 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 ask
22away!
23
24[discussions]: https://github.com/pelletier/go-toml/discussions
25
26## Improve the documentation
27
28The best way to share your knowledge and experience with go-toml is to improve
29the documentation. Fix a typo, clarify an interface, add an example, anything
30goes!
31
32The documentation is present in the [README][readme] and thorough the source
33code. On release, it gets updated on [pkg.go.dev][pkg.go.dev]. To make a change
34to the documentation, create a pull request with your proposed changes. For
35simple changes like that, the easiest way to go is probably the "Fork this
36project and edit the file" button on Github, displayed at the top right of the
37file. Unless it's a trivial change (for example a typo), provide a little bit of
38context in your pull request description or commit message.
39
40## Report a bug
41
42Found a bug! Sorry to hear that :(. Help us and other track them down and fix by
43reporting it. [File a new bug report][bug-report] on the [issues
44tracker][issues-tracker]. The template should provide enough guidance on what to
45include. When in doubt: add more details! By reducing ambiguity and providing
46more information, it decreases back and forth and saves everyone time.
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 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
67It does sound like a lot, but those best practices are here to save time overall
68and continuously improve the quality of the project, which is something everyone
69benefits 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.
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 -race ./...`.
87
88During the pull request process, all tests will be ran on Linux, Windows, and
89MacOS on the last two versions of Go.
90
91However, given GitHub's new policy to _not_ run Actions on pull requests until a
92maintainer clicks on button, it is highly recommended that you run them locally
93as you make changes.
94
95### Check coverage
96
97We use `go tool cover` to compute test coverage. Most code editors have a way to
98run and display code coverage, but at the end of the day, we do this:
99
100```
101go test -covermode=atomic -coverprofile=coverage.out
102go tool cover -func=coverage.out
103```
104
105and verify that the overall percentage of tested code does not go down. This is
106a requirement. As a rule of thumb, all lines of code touched by your changes
107should be covered. On Unix you can use `./ci.sh coverage -d v2` to check if your
108code lowers the coverage.
109
110### Verify performance
111
112Go-toml aims to stay efficient. We rely on a set of scenarios executed with Go's
113builtin benchmark systems. Because of their noisy nature, containers provided by
114Github Actions cannot be reliably used for benchmarking. As a result, you are
115responsible for checking that your changes do not incur a performance penalty.
116You can run their following to execute benchmarks:
117
118```
119go test ./... -bench=. -count=10
120```
121
122Benchmark results should be compared against each other with
123[benchstat][benchstat]. Typical flow looks like this:
124
1251. On the `v2` branch, run `go test ./... -bench=. -count 10` and save output to
126 a file (for example `old.txt`).
1272. Make some code changes.
1283. Run `go test ....` again, and save the output to an other file (for example
129 `new.txt`).
1304. Run `benchstat old.txt new.txt` to check that time/op does not go up in any
131 test.
132
133On Unix you can use `./ci.sh benchmark -d v2` to verify how your code impacts
134performance.
135
136It is highly encouraged to add the benchstat results to your pull request
137description. 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
143Try to look around and follow the same format and structure as the rest of the
144code. We enforce using `go fmt` on the whole code base.
145
146---
147
148## Maintainers-only
149
150### Merge pull request
151
152Checklist:
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
1611. Merge using "squash and merge".
1622. Make sure to edit the commit message to keep all the useful information
163 nice and clean.
1643. Make sure the commit title is clear and contains the PR number (#123).
165
166### New release
167
1681. Decide on the next version number. Use semver.
1692. 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```
1783. 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.
1814. [Draft new release][new-release].
1825. Fill tag and target with the same value used to generate the changelog.
1836. Set title to the new tag value.
1847. Paste the generated changelog.
1858. Check "create discussion", in the "Releases" category.
1869. 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
View as plain text