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.