251
|
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 TOML |
|
7 |
implementation for Go that gets the job done and gets out of your way – |
|
8 |
dealing 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 |
|
11 |
small, is more than welcomed! |
|
12 |
|
|
13 |
### Ask questions |
|
14 |
|
|
15 |
Any question you may have, somebody else might have it too. Always feel |
|
16 |
free to ask them on the [issues tracker][issues-tracker]. We will try to |
|
17 |
answer them as 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 |
|
22 |
ask away! |
|
23 |
|
|
24 |
### Improve the documentation |
|
25 |
|
|
26 |
The best way to share your knowledge and experience with go-toml is to |
|
27 |
improve the documentation. Fix a typo, clarify an interface, add an |
|
28 |
example, anything goes! |
|
29 |
|
|
30 |
The documentation is present in the [README][readme] and thorough the |
|
31 |
source code. On release, it gets updated on [GoDoc][godoc]. To make a |
|
32 |
change to the documentation, create a pull request with your proposed |
|
33 |
changes. For simple changes like that, the easiest way to go is probably |
|
34 |
the "Fork this project and edit the file" button on Github, displayed at |
|
35 |
the top right of the file. Unless it's a trivial change (for example a |
|
36 |
typo), provide a little bit of context in your pull request description or |
|
37 |
commit message. |
|
38 |
|
|
39 |
### Report a bug |
|
40 |
|
|
41 |
Found a bug! Sorry to hear that :(. Help us and other track them down and |
|
42 |
fix by reporting it. [File a new bug report][bug-report] on the [issues |
|
43 |
tracker][issues-tracker]. The template should provide enough guidance on |
|
44 |
what to include. When in doubt: add more details! By reducing ambiguity and |
|
45 |
providing more information, it decreases back and forth and saves everyone |
|
46 |
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 |
|
55 |
text with no code. Code speaks louder than words. |
|
56 |
* No backward-incompatible patch will be accepted unless discussed. |
|
57 |
Sometimes it's hard, and Go's lack of versioning by default does not |
|
58 |
help, 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 |
|
61 |
to 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 |
|
65 |
already included in the PR description. |
|
66 |
|
|
67 |
It does sound like a lot, but those best practices are here to save time |
|
68 |
overall and continuously improve the quality of the project, which is |
|
69 |
something everyone 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. You're in! |
|
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 ./...`. |
|
87 |
When creating a pull requests, all tests will be ran on Linux on a few Go |
|
88 |
versions (Travis CI), and on Windows using the latest Go version |
|
89 |
(AppVeyor). |
|
90 |
|
|
91 |
#### Style |
|
92 |
|
|
93 |
Try to look around and follow the same format and structure as the rest of |
|
94 |
the code. We enforce using `go fmt` on the whole code base. |
|
95 |
|
|
96 |
--- |
|
97 |
|
|
98 |
### Maintainers-only |
|
99 |
|
|
100 |
#### Merge pull request |
|
101 |
|
|
102 |
Checklist: |
|
103 |
|
|
104 |
* Passing CI. |
|
105 |
* Does not introduce backward-incompatible changes (unless discussed). |
|
106 |
* Has relevant doc changes. |
|
107 |
* Has relevant unit tests. |
|
108 |
|
|
109 |
1. Merge using "squash and merge". |
|
110 |
2. Make sure to edit the commit message to keep all the useful information |
|
111 |
nice and clean. |
|
112 |
3. Make sure the commit title is clear and contains the PR number (#123). |
|
113 |
|
|
114 |
#### New release |
|
115 |
|
|
116 |
1. Go to [releases][releases]. Click on "X commits to master since this |
|
117 |
release". |
|
118 |
2. Make note of all the changes. Look for backward incompatible changes, |
|
119 |
new features, and bug fixes. |
|
120 |
3. Pick the new version using the above and semver. |
|
121 |
4. Create a [new release][new-release]. |
|
122 |
5. Follow the same format as [1.1.0][release-110]. |
|
123 |
|
|
124 |
[issues-tracker]: https://github.com/pelletier/go-toml/issues |
|
125 |
[bug-report]: https://github.com/pelletier/go-toml/issues/new?template=bug_report.md |
|
126 |
[godoc]: https://godoc.org/github.com/pelletier/go-toml |
|
127 |
[readme]: ./README.md |
|
128 |
[fork]: https://help.github.com/articles/fork-a-repo |
|
129 |
[pull-request]: https://help.github.com/en/articles/creating-a-pull-request |
|
130 |
[releases]: https://github.com/pelletier/go-toml/releases |
|
131 |
[new-release]: https://github.com/pelletier/go-toml/releases/new |
|
132 |
[release-110]: https://github.com/pelletier/go-toml/releases/tag/v1.1.0 |