mirror of
https://github.com/cwinfo/matterbridge.git
synced 2024-11-30 01:31:36 +00:00
133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
## Contributing
|
||
|
||
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 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!
|
||
|
||
### Ask questions
|
||
|
||
Any question you may have, somebody else might have it too. Always feel
|
||
free to ask them on the [issues tracker][issues-tracker]. 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!
|
||
|
||
### Improve the documentation
|
||
|
||
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][readme] and thorough the
|
||
source code. On release, it gets updated on [GoDoc][godoc]. 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.
|
||
|
||
### Report a bug
|
||
|
||
Found a bug! Sorry to hear that :(. Help us and other track them down and
|
||
fix by reporting it. [File a new bug report][bug-report] on the [issues
|
||
tracker][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.
|
||
|
||
### Code changes
|
||
|
||
Want to contribute a patch? Very happy to hear that!
|
||
|
||
First, some high-level rules:
|
||
|
||
* A short proposal with some POC code is better than a lengthy piece of
|
||
text with no code. Code speaks louder than words.
|
||
* No backward-incompatible patch will be accepted unless discussed.
|
||
Sometimes it's hard, and Go's lack of versioning by default does not
|
||
help, but we try not to break people's programs unless we absolutely have
|
||
to.
|
||
* If you are writing a new feature or extending an existing one, make sure
|
||
to write some documentation.
|
||
* Bug fixes need to be accompanied with regression tests.
|
||
* New code needs to be tested.
|
||
* Your commit messages need to explain why the change is needed, even if
|
||
already included in the PR description.
|
||
|
||
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.
|
||
|
||
#### Get started
|
||
|
||
The fairly standard code contribution process looks like that:
|
||
|
||
1. [Fork the project][fork].
|
||
2. Make your changes, commit on any branch you like.
|
||
3. [Open up a pull request][pull-request]
|
||
4. Review, potential ask for changes.
|
||
5. Merge. You're in!
|
||
|
||
Feel free to ask for help! You can create draft pull requests to gather
|
||
some early feedback!
|
||
|
||
#### Run the tests
|
||
|
||
You can run tests for go-toml using Go's test tool: `go test ./...`.
|
||
When creating a pull requests, all tests will be ran on Linux on a few Go
|
||
versions (Travis CI), and on Windows using the latest Go version
|
||
(AppVeyor).
|
||
|
||
#### Style
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
### Maintainers-only
|
||
|
||
#### Merge pull request
|
||
|
||
Checklist:
|
||
|
||
* Passing CI.
|
||
* Does not introduce backward-incompatible changes (unless discussed).
|
||
* Has relevant doc changes.
|
||
* Has relevant unit tests.
|
||
|
||
1. Merge using "squash and merge".
|
||
2. Make sure to edit the commit message to keep all the useful information
|
||
nice and clean.
|
||
3. Make sure the commit title is clear and contains the PR number (#123).
|
||
|
||
#### New release
|
||
|
||
1. Go to [releases][releases]. Click on "X commits to master since this
|
||
release".
|
||
2. Make note of all the changes. Look for backward incompatible changes,
|
||
new features, and bug fixes.
|
||
3. Pick the new version using the above and semver.
|
||
4. Create a [new release][new-release].
|
||
5. Follow the same format as [1.1.0][release-110].
|
||
|
||
[issues-tracker]: https://github.com/pelletier/go-toml/issues
|
||
[bug-report]: https://github.com/pelletier/go-toml/issues/new?template=bug_report.md
|
||
[godoc]: https://godoc.org/github.com/pelletier/go-toml
|
||
[readme]: ./README.md
|
||
[fork]: https://help.github.com/articles/fork-a-repo
|
||
[pull-request]: https://help.github.com/en/articles/creating-a-pull-request
|
||
[releases]: https://github.com/pelletier/go-toml/releases
|
||
[new-release]: https://github.com/pelletier/go-toml/releases/new
|
||
[release-110]: https://github.com/pelletier/go-toml/releases/tag/v1.1.0
|