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