Thank you for your interest in go-toml! We appreciate you considering contributing to go-toml!
The main goal is the project is to provide an easy-to-use and efficient TOML implementation for Go that gets the job done and gets out of your way – dealing with TOML is probably not the central piece of your project.
As the single maintainer of go-toml, time is scarce. All help, big or small, is more than welcomed!
Any question you may have, somebody else might have it too. Always feel free to ask them on the discussion board. We will try to answer them as clearly and quickly as possible, time permitting.
Asking questions also helps us identify areas where the documentation needs improvement, or new features that weren't envisioned before. Sometimes, a seemingly innocent question leads to the fix of a bug. Don't hesitate and ask away!
The best way to share your knowledge and experience with go-toml is to improve the documentation. Fix a typo, clarify an interface, add an example, anything goes!
The documentation is present in the README and thorough the source code. On release, it gets updated on pkg.go.dev. To make a change to the documentation, create a pull request with your proposed changes. For simple changes like that, the easiest way to go is probably the "Fork this project and edit the file" button on Github, displayed at the top right of the file. Unless it's a trivial change (for example a typo), provide a little bit of context in your pull request description or commit message.
Found a bug! Sorry to hear that :(. Help us and other track them down and fix by reporting it. File a new bug report on the issues tracker. The template should provide enough guidance on what to include. When in doubt: add more details! By reducing ambiguity and providing more information, it decreases back and forth and saves everyone time.
Want to contribute a patch? Very happy to hear that!
First, some high-level rules:
It does sound like a lot, but those best practices are here to save time overall and continuously improve the quality of the project, which is something everyone benefits from.
The fairly standard code contribution process looks like that:
Feel free to ask for help! You can create draft pull requests to gather some early feedback!
You can run tests for go-toml using Go's test tool: go test -race ./...
.
During the pull request process, all tests will be ran on Linux, Windows, and MacOS on the last two versions of Go.
However, given GitHub's new policy to not run Actions on pull requests until a maintainer clicks on button, it is highly recommended that you run them locally as you make changes.
We use go tool cover
to compute test coverage. Most code editors have a way to
run and display code coverage, but at the end of the day, we do this:
go test -covermode=atomic -coverprofile=coverage.out
go tool cover -func=coverage.out
and verify that the overall percentage of tested code does not go down. This is
a requirement. As a rule of thumb, all lines of code touched by your changes
should be covered. On Unix you can use ./ci.sh coverage -d v2
to check if your
code lowers the coverage.
Go-toml aims to stay efficient. We rely on a set of scenarios executed with Go's builtin benchmark systems. Because of their noisy nature, containers provided by Github Actions cannot be reliably used for benchmarking. As a result, you are responsible for checking that your changes do not incur a performance penalty. You can run their following to execute benchmarks:
go test ./... -bench=. -count=10
Benchmark results should be compared against each other with benchstat. Typical flow looks like this:
v2
branch, run go test ./... -bench=. -count 10
and save output to
a file (for example old.txt
).go test ....
again, and save the output to an other file (for example
new.txt
).benchstat old.txt new.txt
to check that time/op does not go up in any
test.On Unix you can use ./ci.sh benchmark -d v2
to verify how your code impacts
performance.
It is highly encouraged to add the benchstat results to your pull request description. Pull requests that lower performance will receive more scrutiny.
Try to look around and follow the same format and structure as the rest of the
code. We enforce using go fmt
on the whole code base.
Checklist:
Generate release notes using gh
. Example:
$ gh api -X POST \
-F tag_name='v2.0.0-beta.5' \
-F target_commitish='v2' \
-F previous_tag_name='v2.0.0-beta.4' \
--jq '.body' \
repos/pelletier/go-toml/releases/generate-notes
Look for "Other changes". That would indicate a pull request not labeled properly. Tweak labels and pull request titles until changelog looks good for users.
Fill tag and target with the same value used to generate the changelog.
Set title to the new tag value.
Paste the generated changelog.
Check "create discussion", in the "Releases" category.
Check pre-release if new version is an alpha or beta.