github.com/mckael/restic@v0.8.3/CONTRIBUTING.md (about)

     1  This document describes the way you can contribute to the restic project.
     2  
     3  Ways to Help Out
     4  ================
     5  
     6  Thank you for your contribution! Please **open an issue first** (or add a
     7  comment to an existing issue) if you plan to work on any code or add a new
     8  feature. This way, duplicate work is prevented and we can discuss your ideas
     9  and design first.
    10  
    11  There are several ways you can help us out. First of all code contributions and
    12  bug fixes are most welcome. However even "minor" details as fixing spelling
    13  errors, improving documentation or pointing out usability issues are a great
    14  help also.
    15  
    16  
    17  The restic project uses the GitHub infrastructure (see the
    18  [project page](https://github.com/restic/restic)) for all related discussions
    19  as well as the `#restic` channel on `irc.freenode.net`.
    20  
    21  If you want to find an area that currently needs improving have a look at the
    22  open issues listed at the
    23  [issues page](https://github.com/restic/restic/issues). This is also the place
    24  for discussing enhancement to the restic tools.
    25  
    26  If you are unsure what to do, please have a look at the issues, especially
    27  those tagged
    28  [minor complexity](https://github.com/restic/restic/labels/minor%20complexity).
    29  
    30  
    31  Reporting Bugs
    32  ==============
    33  
    34  You've found a bug? Thanks for letting us know so we can fix it! It is a good
    35  idea to describe in detail how to reproduce the bug (when you know how), what
    36  environment was used and so on. Please tell us at least the following things:
    37  
    38   * What's the version of restic you used? Please include the output of
    39     `restic version` in your bug report.
    40   * What commands did you execute to get to where the bug occurred?
    41   * What did you expect?
    42   * What happened instead?
    43   * Are you aware of a way to reproduce the bug?
    44  
    45  Remember, the easier it is for us to reproduce the bug, the earlier it will be
    46  corrected!
    47  
    48  In addition, you can compile restic with debug support by running
    49  `go run build.go -tags debug` and instructing it to create a debug log by
    50  setting the environment variable `DEBUG_LOG` to a file, e.g. like this:
    51  
    52      $ export DEBUG_LOG=/tmp/restic-debug.log
    53      $ restic backup ~/work
    54  
    55  Please be aware that the debug log file will contain potentially sensitive
    56  things like file and directory names, so please either redact it before
    57  uploading it somewhere or post only the parts that are really relevant.
    58  
    59  
    60  Development Environment
    61  =======================
    62  
    63  In order to compile restic with the `go` tool directly, it needs to be checked
    64  out at the right path within a `GOPATH`. The concept of a `GOPATH` is explained
    65  in ["How to write Go code"](https://golang.org/doc/code.html).
    66  
    67  If you do not have a directory with Go code yet, executing the following
    68  instructions in your shell will create one for you and check out the restic
    69  repo:
    70  
    71      $ export GOPATH="$HOME/go"
    72      $ mkdir -p "$GOPATH/src/github.com/restic"
    73      $ cd "$GOPATH/src/github.com/restic"
    74      $ git clone https://github.com/restic/restic
    75      $ cd restic
    76  
    77  You can then build restic as follows:
    78  
    79      $ go build ./cmd/restic
    80      $ ./restic version
    81      restic compiled manually
    82      compiled with go1.8.3 on linux/amd64
    83  
    84  The following commands can be used to run all the tests:
    85  
    86      $ go test ./cmd/... ./internal/...
    87  
    88  The repository contains two sets of directories with code: `cmd/` and
    89  `internal/` contain the code written for restic, whereas `vendor/` contains
    90  copies of libraries restic depends on. The libraries are managed with the
    91  [`dep`](https://github.com/golang/dep) tool.
    92  
    93  Providing Patches
    94  =================
    95  
    96  You have fixed an annoying bug or have added a new feature? Very cool! Let's
    97  get it into the project! The workflow we're using is also described on the
    98  [GitHub Flow](https://guides.github.com/introduction/flow/) website, it boils
    99  down to the following steps:
   100  
   101   0. If you want to work on something, please add a comment to the issue on
   102      GitHub. For a new feature, please add an issue before starting to work on
   103      it, so that duplicate work is prevented.
   104  
   105   1. First we would kindly ask you to fork our project on GitHub if you haven't
   106      done so already.
   107  
   108   2. Clone the repository locally and create a new branch. If you are working on
   109      the code itself, please set up the development environment as described in
   110      the previous section. Especially take care to place your forked repository
   111      at the correct path (`src/github.com/restic/restic`) within your `GOPATH`.
   112  
   113   3. Then commit your changes as fine grained as possible, as smaller patches,
   114      that handle one and only one issue are easier to discuss and merge.
   115  
   116   4. Push the new branch with your changes to your fork of the repository.
   117  
   118   5. Create a pull request by visiting the GitHub website, it will guide you
   119      through the process.
   120  
   121   6. You will receive comments on your code and the feature or bug that they
   122      address. Maybe you need to rework some minor things, in this case push new
   123      commits to the branch you created for the pull request (or amend the
   124      existing commit, use common sense to decide which is better), they will be
   125      automatically added to the pull request.
   126  
   127   7. If your pull request changes anything that users should be aware of (a
   128      bugfix, a new feature, ...) please add an entry to the file
   129      ['CHANGELOG.md'](CHANGELOG.md). It will be used in the announcement of the
   130      next stable release. While writing, ask yourself: If I were the user, what
   131      would I need to be aware of with this change.
   132  
   133   8. Once your code looks good and passes all the tests, we'll merge it. Thanks
   134      a lot for your contribution!
   135  
   136  Please provide the patches for each bug or feature in a separate branch and
   137  open up a pull request for each.
   138  
   139  The restic project uses the `gofmt` tool for Go source indentation, so please
   140  run
   141  
   142      gofmt -w **/*.go
   143  
   144  in the project root directory before committing. Installing the script
   145  `fmt-check` from https://github.com/edsrzf/gofmt-git-hook locally as a
   146  pre-commit hook checks formatting before committing automatically, just copy
   147  this script to `.git/hooks/pre-commit`.
   148  
   149  For each pull request, several different systems run the integration tests on
   150  Linux, OS X and Windows. We won't merge any code that does not pass all tests
   151  for all systems, so when a tests fails, try to find out what's wrong and fix
   152  it. If you need help on this, please leave a comment in the pull request, and
   153  we'll be glad to assist. Having a PR with failing integration tests is nothing
   154  to be ashamed of. In contrast, that happens regularly for all of us. That's
   155  what the tests are there for.
   156  
   157  Git Commits
   158  -----------
   159  
   160  It would be good if you could follow the same general style regarding Git
   161  commits as the rest of the project, this makes reviewing code, browsing the
   162  history and triaging bugs much easier.
   163  
   164  Git commit messages have a very terse summary in the first line of the commit
   165  message, followed by an empty line, followed by a more verbose description or a
   166  List of changed things. For examples, please refer to the excellent [How to
   167  Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
   168  
   169  If you change/add multiple different things that aren't related at all, try to
   170  make several smaller commits. This is much easier to review. Using `git add -p`
   171  allows staging and committing only some changes.
   172  
   173  Code Review
   174  ===========
   175  
   176  The restic project encourages actively reviewing the code, as it will store
   177  your precious data, so it's common practice to receive comments on provided
   178  patches.
   179  
   180  If you are reviewing other contributor's code please consider the following
   181  when reviewing:
   182  
   183  * Be nice. Please make the review comment as constructive as possible so all
   184    participants will learn something from your review.
   185  
   186  As a contributor you might be asked to rewrite portions of your code to make it
   187  fit better into the upstream sources.