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