github.com/serversong/goreporter@v0.0.0-20200325104552-3cfaf44fd178/CONTRIBUTING.md (about) 1 # Contributing to GoReporter 2 3 Want to hack on GoReporter? Awesome! This page contains information about reporting issues as well as some tips and 4 guidelines useful to experienced open source contributors. Finally, make sure 5 you read our [community guidelines](#goreporter-community-guidelines) before you 6 start participating. 7 8 ## Topics 9 10 * [Reporting Security Issues](#reporting-security-issues) 11 * [Design and Cleanup Proposals](#design-and-cleanup-proposals) 12 * [Reporting Issues](#reporting-other-issues) 13 * [Quick Contribution Tips and Guidelines](#quick-contribution-tips-and-guidelines) 14 * [Community Guidelines](#community-guidelines) 15 16 ## Reporting security issues 17 18 The GoReporter maintainers take security seriously. If you discover a security 19 issue, please bring it to their attention right away! 20 21 Please **DO NOT** file a public issue, instead send your report privately to 22 [iamwgliang@email.com](mailto:iamwgliang@email.com). 23 24 Security reports are greatly appreciated and we will publicly thank you for it. 25 We currently do not offer a paid security bounty program, but are not 26 ruling it out in the future. 27 28 29 ## Reporting other issues 30 31 A great way to contribute to the project is to send a detailed report when you 32 encounter an issue. We always appreciate a well-written, thorough bug report, 33 and will thank you for it! 34 35 Check that [our issue database](https://github.com/360EntSecGroup-Skylar/goreporter/issues) 36 doesn't already include that problem or suggestion before submitting an issue. 37 If you find a match, you can use the "subscribe" button to get notified on 38 updates. Do *not* leave random "+1" or "I have this too" comments, as they 39 only clutter the discussion, and don't help resolving it. However, if you 40 have ways to reproduce the issue or have additional information that may help 41 resolving the issue, please leave a comment. 42 43 When reporting issues, always include the output of `go env`. 44 45 Also include the steps required to reproduce the problem if possible and 46 applicable. This information will help us review and fix your issue faster. 47 When sending lengthy log-files, consider posting them as a gist (https://gist.github.com). 48 Don't forget to remove sensitive data from your logfiles before posting (you can 49 replace those parts with "REDACTED"). 50 51 ## Quick contribution tips and guidelines 52 53 This section gives the experienced contributor some tips and guidelines. 54 55 ### Pull requests are always welcome 56 57 Not sure if that typo is worth a pull request? Found a bug and know how to fix 58 it? Do it! We will appreciate it. Any significant improvement should be 59 documented as [a GitHub issue](https://github.com/360EntSecGroup-Skylar/goreporter/issues) before 60 anybody starts working on it. 61 62 We are always thrilled to receive pull requests. We do our best to process them 63 quickly. If your pull request is not accepted on the first try, 64 don't get discouraged! 65 66 ### Design and cleanup proposals 67 68 You can propose new designs for existing GoReporter features. You can also design 69 entirely new features. We really appreciate contributors who want to refactor or 70 otherwise cleanup our project. 71 72 We try hard to keep GoReporter lean and focused. GoReporter can't do everything for 73 everybody. This means that we might decide against incorporating a new feature. 74 However, there might be a way to implement that feature *on top of* GoReporter. 75 76 ### Conventions 77 78 Fork the repository and make changes on your fork in a feature branch: 79 80 - If it's a bug fix branch, name it XXXX-something where XXXX is the number of 81 the issue. 82 - If it's a feature branch, create an enhancement issue to announce 83 your intentions, and name it XXXX-something where XXXX is the number of the 84 issue. 85 86 Submit unit tests for your changes. Go has a great test framework built in; use 87 it! Take a look at existing tests for inspiration. Run the full test on your branch before 88 submitting a pull request. 89 90 Update the documentation when creating or modifying features. Test your 91 documentation changes for clarity, concision, and correctness, as well as a 92 clean documentation build. 93 94 Write clean code. Universally formatted code promotes ease of writing, reading, 95 and maintenance. Always run `gofmt -s -w file.go` on each changed file before 96 committing your changes. Most editors have plug-ins that do this automatically. 97 98 Pull request descriptions should be as clear as possible and include a reference 99 to all the issues that they address. 100 101 ### Successful Changes 102 103 Before contributing large or high impact changes, make the effort to coordinate 104 with the maintainers of the project before submitting a pull request. This 105 prevents you from doing extra work that may or may not be merged. 106 107 Large PRs that are just submitted without any prior communication are unlikely 108 to be successful. 109 110 While pull requests are the methodology for submitting changes to code, changes 111 are much more likely to be accepted if they are accompanied by additional 112 engineering work. While we don't define this explicitly, most of these goals 113 are accomplished through communication of the design goals and subsequent 114 solutions. Often times, it helps to first state the problem before presenting 115 solutions. 116 117 Typically, the best methods of accomplishing this are to submit an issue, 118 stating the problem. This issue can include a problem statement and a 119 checklist with requirements. If solutions are proposed, alternatives should be 120 listed and eliminated. Even if the criteria for elimination of a solution is 121 frivolous, say so. 122 123 Larger changes typically work best with design documents. These are focused on 124 providing context to the design at the time the feature was conceived and can 125 inform future documentation contributions. 126 127 ### Commit Messages 128 129 Commit messages must start with a capitalized and short summary 130 written in the imperative, followed by an optional, more detailed explanatory 131 text which is separated from the summary by an empty line. 132 133 Commit messages should follow best practices, including explaining the context 134 of the problem and how it was solved, including in caveats or follow up changes 135 required. They should tell the story of the change and provide readers 136 understanding of what led to it. 137 138 In practice, the best approach to maintaining a nice commit message is to 139 leverage a `git add -p` and `git commit --amend` to formulate a solid 140 changeset. This allows one to piece together a change, as information becomes 141 available. 142 143 If you squash a series of commits, don't just submit that. Re-write the commit 144 message, as if the series of commits was a single stroke of brilliance. 145 146 That said, there is no requirement to have a single commit for a PR, as long as 147 each commit tells the story. For example, if there is a feature that requires a 148 package, it might make sense to have the package in a separate commit then have 149 a subsequent commit that uses it. 150 151 Remember, you're telling part of the story with the commit message. Don't make 152 your chapter weird. 153 154 ### Review 155 156 Code review comments may be added to your pull request. Discuss, then make the 157 suggested modifications and push additional commits to your feature branch. Post 158 a comment after pushing. New commits show up in the pull request automatically, 159 but the reviewers are notified only when you comment. 160 161 Pull requests must be cleanly rebased on top of master without multiple branches 162 mixed into the PR. 163 164 **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your 165 feature branch to update your pull request rather than `merge master`. 166 167 Before you make a pull request, squash your commits into logical units of work 168 using `git rebase -i` and `git push -f`. A logical unit of work is a consistent 169 set of patches that should be reviewed together: for example, upgrading the 170 version of a vendored dependency and taking advantage of its now available new 171 feature constitute two separate units of work. Implementing a new function and 172 calling it in another file constitute a single logical unit of work. The very 173 high majority of submissions should have a single commit, so if in doubt: squash 174 down to one. 175 176 After every commit, make sure the test passes. Include documentation 177 changes in the same pull request so that a revert would remove all traces of 178 the feature or fix. 179 180 Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in commits that 181 close an issue. Including references automatically closes the issue on a merge. 182 183 Please see the [Coding Style](#coding-style) for further guidelines. 184 185 ### Merge approval 186 187 GoReporter maintainers use LGTM (Looks Good To Me) in comments on the code review to 188 indicate acceptance. 189 190 ### Sign your work 191 192 The sign-off is a simple line at the end of the explanation for the patch. Your 193 signature certifies that you wrote the patch or otherwise have the right to pass 194 it on as an open-source patch. The rules are pretty simple: if you can certify 195 the below (from [developercertificate.org](http://developercertificate.org/)): 196 197 ``` 198 Developer Certificate of Origin 199 Version 1.1 200 201 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 202 1 Letterman Drive 203 Suite D4700 204 San Francisco, CA, 94129 205 206 Everyone is permitted to copy and distribute verbatim copies of this 207 license document, but changing it is not allowed. 208 209 Developer's Certificate of Origin 1.1 210 211 By making a contribution to this project, I certify that: 212 213 (a) The contribution was created in whole or in part by me and I 214 have the right to submit it under the open source license 215 indicated in the file; or 216 217 (b) The contribution is based upon previous work that, to the best 218 of my knowledge, is covered under an appropriate open source 219 license and I have the right under that license to submit that 220 work with modifications, whether created in whole or in part 221 by me, under the same open source license (unless I am 222 permitted to submit under a different license), as indicated 223 in the file; or 224 225 (c) The contribution was provided directly to me by some other 226 person who certified (a), (b) or (c) and I have not modified 227 it. 228 229 (d) I understand and agree that this project and the contribution 230 are public and that a record of the contribution (including all 231 personal information I submit with it, including my sign-off) is 232 maintained indefinitely and may be redistributed consistent with 233 this project or the open source license(s) involved. 234 ``` 235 236 Then you just add a line to every git commit message: 237 238 Signed-off-by: Jack Wang <iamwgliang@email.com> 239 240 Use your real name (sorry, no pseudonyms or anonymous contributions.) 241 242 If you set your `user.name` and `user.email` git configs, you can sign your 243 commit automatically with `git commit -s`. 244 245 ### How can I become a maintainer? 246 247 First, all maintainers have 3 things 248 249 - They share responsibility in the project's success. 250 - They have made a long-term, recurring time investment to improve the project. 251 - They spend that time doing whatever needs to be done, not necessarily what 252 is the most interesting or fun. 253 254 Maintainers are often under-appreciated, because their work is harder to appreciate. 255 It's easy to appreciate a really cool and technically advanced feature. It's harder 256 to appreciate the absence of bugs, the slow but steady improvement in stability, 257 or the reliability of a release process. But those things distinguish a good 258 project from a great one. 259 260 Don't forget: being a maintainer is a time investment. Make sure you 261 will have time to make yourself available. You don't have to be a 262 maintainer to make a difference on the project! 263 264 If you want to become a meintainer, contact Jack Wang <iamwgliang@email.com> and given a introduction of you. 265 266 ## Community guidelines 267 268 We want to keep the community awesome, growing and collaborative. We need 269 your help to keep it that way. To help with this we've come up with some general 270 guidelines for the community as a whole: 271 272 * Be nice: Be courteous, respectful and polite to fellow community members: 273 no regional, racial, gender, or other abuse will be tolerated. We like 274 nice people way better than mean ones! 275 276 * Encourage diversity and participation: Make everyone in our community feel 277 welcome, regardless of their background and the extent of their 278 contributions, and do everything possible to encourage participation in 279 our community. 280 281 * Keep it legal: Basically, don't get us in trouble. Share only content that 282 you own, do not share private or sensitive information, and don't break 283 the law. 284 285 * Stay on topic: Make sure that you are posting to the correct channel and 286 avoid off-topic discussions. Remember when you update an issue or respond 287 to an email you are potentially sending to a large number of people. Please 288 consider this before you update. Also remember that nobody likes spam. 289 290 * Don't send email to the maintainers: There's no need to send email to the 291 maintainers to ask them to investigate an issue or to take a look at a 292 pull request. Instead of sending an email, GitHub mentions should be 293 used to ping maintainers to review a pull request, a proposal or an 294 issue. 295 296 ### Guideline violations — 3 strikes method 297 298 The point of this section is not to find opportunities to punish people, but we 299 do need a fair way to deal with people who are making our community suck. 300 301 1. First occurrence: We'll give you a friendly, but public reminder that the 302 behavior is inappropriate according to our guidelines. 303 304 2. Second occurrence: We will send you a private message with a warning that 305 any additional violations will result in removal from the community. 306 307 3. Third occurrence: Depending on the violation, we may need to delete or ban 308 your account. 309 310 **Notes:** 311 312 * Obvious spammers are banned on first occurrence. If we don't do this, we'll 313 have spam all over the place. 314 315 * Violations are forgiven after 6 months of good behavior, and we won't hold a 316 grudge. 317 318 * People who commit minor infractions will get some education, rather than 319 hammering them in the 3 strikes process. 320 321 * The rules apply equally to everyone in the community, no matter how much 322 you've contributed. 323 324 * Extreme violations of a threatening, abusive, destructive or illegal nature 325 will be addressed immediately and are not subject to 3 strikes or forgiveness. 326 327 * Contact Jack Wang <iamwgliang@email.com> to report abuse or appeal violations. In the case of 328 appeals, we know that mistakes happen, and we'll work with you to come up with a 329 fair solution if there has been a misunderstanding. 330 331 ## Coding Style 332 333 Unless explicitly stated, we follow all coding guidelines from the Go 334 community. While some of these standards may seem arbitrary, they somehow seem 335 to result in a solid, consistent codebase. 336 337 It is possible that the code base does not currently comply with these 338 guidelines. We are not looking for a massive PR that fixes this, since that 339 goes against the spirit of the guidelines. All new contributions should make a 340 best effort to clean up and make the code base better than they left it. 341 Obviously, apply your best judgement. Remember, the goal here is to make the 342 code base easier for humans to navigate and understand. Always keep that in 343 mind when nudging others to comply. 344 345 The rules: 346 347 1. All code should be formatted with `gofmt -s`. 348 2. All code should pass the default levels of 349 [`golint`](https://github.com/golang/lint). 350 3. All code should follow the guidelines covered in [Effective 351 Go](http://golang.org/doc/effective_go.html) and [Go Code Review 352 Comments](https://github.com/golang/go/wiki/CodeReviewComments). 353 4. Comment the code. Tell us the why, the history and the context. 354 5. Document _all_ declarations and methods, even private ones. Declare 355 expectations, caveats and anything else that may be important. If a type 356 gets exported, having the comments already there will ensure it's ready. 357 6. Variable name length should be proportional to its context and no longer. 358 `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`. 359 In practice, short methods will have short variable names and globals will 360 have longer names. 361 7. No underscores in package names. If you need a compound name, step back, 362 and re-examine why you need a compound name. If you still think you need a 363 compound name, lose the underscore. 364 8. No utils or helpers packages. If a function is not general enough to 365 warrant its own package, it has not been written generally enough to be a 366 part of a util package. Just leave it unexported and well-documented. 367 9. All tests should run with `go test` and outside tooling should not be 368 required. No, we don't need another unit testing framework. Assertion 369 packages are acceptable if they provide _real_ incremental value. 370 10. Even though we call these "rules" above, they are actually just 371 guidelines. Since you've read all the rules, you now know that. 372 373 If you are having trouble getting into the mood of idiomatic Go, we recommend 374 reading through [Effective Go](https://golang.org/doc/effective_go.html). The 375 [Go Blog](https://blog.golang.org) is also a great resource. Drinking the 376 kool-aid is a lot easier than going thirsty.