|
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 |