github.com/mutagen-io/mutagen@v0.18.0-rc1/CONTRIBUTING.md (about)

     1  # Contributing
     2  
     3  Mutagen welcomes community contributions, especially feedback and experience
     4  reports. See below for more information on the best channels for each of these.
     5  
     6  
     7  ## Issues
     8  
     9  Issues are best submitted via the
    10  [issue tracker](https://github.com/mutagen-io/mutagen/issues). If you're
    11  reporting a security issue (or even just something that you *think* might be a
    12  security issue), then please follow responsible disclosure practices and submit
    13  the issue report using the instructions found in the
    14  [security documentation](SECURITY.md).
    15  
    16  
    17  ## Experience reports
    18  
    19  Experience reports are an essential part of improving Mutagen. These reports
    20  might include problems you've had, use cases that aren't covered by existing
    21  features, or even just general thoughts about how to improve Mutagen. All of
    22  this also applies to Mutagen's website, documentation, and community portals.
    23  You can send your feedback via the
    24  [Mutagen Community Slack Workspace](https://mutagen.io/slack), submit it via the
    25  [issue tracker](https://github.com/mutagen-io/mutagen/issues), or even just
    26  email us at [hello@mutagen.io](mailto:hello@mutagen.io).
    27  
    28  
    29  ## Pull requests
    30  
    31  Before taking the time to implement a change or feature, please discuss the
    32  proposed change on the
    33  [issue tracker](https://github.com/mutagen-io/mutagen/issues) or
    34  [Mutagen Community Slack Workspace](https://mutagen.io/slack).
    35  
    36  If it *does* make sense to open a pull request, please adhere to the following
    37  guidelines. Pull requests that don't follow these guidelines will be closed.
    38  
    39  Pull requesets are not currently accepted for code residing under the `sspl`
    40  directory.
    41  
    42  
    43  ### Developer Certificate of Origin
    44  
    45  Pull requests to Mutagen must be submitted under the terms of the
    46  [Developer Certificate of Origin (DCO)](DCO). In order to accept a pull request,
    47  we require that you sign-off all commits in the pull request using the `-s` flag
    48  with `git commit` to indicate that you agree to the terms of the DCO. You must
    49  also
    50  [cryptographically sign](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
    51  your commits to verify your DCO sign-off.
    52  
    53  
    54  ### Code guidelines
    55  
    56  In order to ensure that Mutagen's codebase remains clean and understandable to
    57  all developers, we kindly request that:
    58  
    59  - Code adheres to Go style guidelines, including those in
    60    [Effective Go](https://go.dev/doc/effective_go) and the
    61    [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
    62  - All code be `go fmt`'d
    63  - New code matches the style and structure of its surrouding code (unless a full
    64    refactor/rewrite of a package is being performed)
    65  - Comments be wrapped at 80 columns (including indentation), with exceptions for
    66    long strings like URLs that shouldn't be broken across lines
    67      - Code does not need to be wrapped at 80 columns, but please do try to keep
    68        lines to a reasonable length
    69  - Comments be used to break up code blocks and be composed of full and complete
    70    sentences
    71    ([example](https://github.com/mutagen-io/mutagen/blob/da724cc1946ff70b9734be3bc5f3aae35c818c99/pkg/synchronization/core/scan.go#L142-L240))
    72  - Imports be grouped by module, with standard library packages in the first
    73    group ([example](https://github.com/mutagen-io/mutagen/blob/da724cc1946ff70b9734be3bc5f3aae35c818c99/cmd/mutagen/forward/create.go#L3-L25))
    74  - Non-trivial changes include full test coverage
    75  
    76  
    77  ### Commit guidelines
    78  
    79  To help keep source control logs readable and useful, we also ask that all
    80  commits have well-formatted commit messages that follow the
    81  [Go commit message guidelines](https://go.dev/doc/contribute#commit_messages),
    82  with no line exceeding 72 characters in length.
    83  
    84  Here's an example of a good message:
    85  
    86      sync: modified controller state locking
    87  
    88      This commit modifies the synchronization controller's state locking to
    89      take into account changes that can occur during shutdown. It requires
    90      that the synchronization Goroutine hold the state lock until fully
    91      terminated.
    92  
    93      Fixes #00000
    94  
    95      Signed-off-by: Jacob Howard <jacob@mutagen.io>
    96  
    97  Here's an example of a not-so-good message:
    98  
    99      fixes sync