1# Contributing
2
3Mutagen welcomes community contributions in all forms, including issue feedback,
4experience reports, and pull requests. See below for more information on the
5best channels for each of these.
6
7
8## Issues
9
10Issues are best submitted via the
11[issue tracker](https://github.com/mutagen-io/mutagen/issues). If you're
12reporting a security issue (or even just something that you *think* might be a
13security issue), then please follow responsible disclosure practices and submit
14the issue report using the instructions found in the
15[security documentation](SECURITY.md).
16
17
18## Experience reports
19
20Experience reports are an essential part of improving Mutagen. These reports
21might include problems you've had, use cases that aren't covered by existing
22features, or even just general thoughts about how to improve Mutagen. All of
23this also applies to Mutagen's website, documentation, and community portals.
24You can send your feedback via the
25[Mutagen community chat](https://spectrum.chat/mutagen/general), submit it via
26the [issue tracker](https://github.com/mutagen-io/mutagen/issues), or even just
27email us at [hello@mutagen.io](mailto:hello@mutagen.io).
28
29
30## Pull requests
31
32Mutagen is happy to receive pull requests and we want to make that procedure as
33painless as possible. To that end, we've outlined a few guidelines to help make
34the process go smoothly.
35
36
37### Developer Certificate of Origin
38
39Pull requests to Mutagen are submitted under the terms of the
40[Developer Certificate of Origin (DCO)](DCO). In order to accept a pull request,
41we require that you sign-off all commits in the pull request using the `-s` flag
42with `git commit` to indicate that you agree to the terms of the DCO.
43
44
45### Code guidelines
46
47In order to ensure that Mutagen's codebase remains clean and understandable to
48newcomers, we kindly request that:
49
50- Code adheres to Go style guidelines, including those in
51  [Effective Go](https://golang.org/doc/effective_go.html) and the
52  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
53- All code be `go fmt`'d
54- Comments be wrapped at 80 columns (with exceptions for long strings like URLs)
55- Comments be used to break up code (see existing code for examples) and be
56  composed of full and complete sentences
57- New code include full test coverage
58
59Basically, when in doubt, new code should share the same style as the
60surrounding code.
61
62
63### Commit guidelines
64
65To help keep source control logs readable and useful, we also ask that all
66commits have well-formatted commit messages composed of a single subject line of
6750-70 characters, followed by a blank line, and finally the full, correctly
68punctuated commit message (also wrapped to 80 lines). We ask the same for the
69pull request message itself.
70
71Here's an example of a good message:
72
73    Modified synchronization controller state locking
74
75    This commit modifies the synchronization controller's state locking to take
76    into account changes that can occur during shutdown. It requires that the
77    synchronization Goroutine hold the state lock until fully terminated.
78
79    Fixes #00000
80
81Here's an example of a not-so-good message:
82
83    fixes sync
84
85
86### Just a heads up...
87
88Please be aware that Mutagen is still at a rapid stage of development, so pull
89requests may be put on the back burner if they conflict with ongoing refactors.
90If you have questions or an idea for a pull request, please reach out on the
91[Mutagen community chat](https://spectrum.chat/mutagen/development) before
92investing a large amount of time writing code. It may be the case that someone
93else is already working on the same thing!
94