restic/CONTRIBUTING.md

192 lines
7.2 KiB
Markdown
Raw Normal View History

2015-05-06 21:18:46 +00:00
This document describes the way you can contribute to the restic project.
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
Ways to Help Out
2015-05-06 07:11:07 +00:00
================
Thank you for your contribution!
2015-05-06 21:18:46 +00:00
There are several ways you can help us out. First of all code contributions and
bug fixes are most welcome. However even "minor" details as fixing spelling
errors, improving documentation or pointing out usability issues are a great
help also.
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
The restic project uses the GitHub infrastructure (see the
[project page](https://github.com/restic/restic)) for all related discussions
as well as the `#restic` channel on `irc.freenode.net`.
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
If you want to find an area that currently needs improving have a look at the
open issues listed at the
[issues page](https://github.com/restic/restic/issues). This is also the place
for discussing enhancement to the restic tools.
If you are unsure what to do, please have a look at the issues, especially
those tagged
[minor complexity](https://github.com/restic/restic/labels/minor%20complexity).
2015-06-24 17:20:27 +00:00
2015-11-05 22:09:01 +00:00
Reporting Bugs
==============
You've found a bug? Thanks for letting us know so we can fix it! It is a good
idea to describe in detail how to reproduce the bug (when you know how), what
environment was used and so on. Please tell us at least the following things:
* What's the version of restic you used? Please include the output of
`restic version` in your bug report.
* What commands did you execute to get to where the bug occurred?
* What did you expect?
* What happened instead?
* Are you aware of a way to reproduce the bug?
2015-11-05 22:10:35 +00:00
Remember, the easier it is for us to reproduce the bug, the earlier it will be
corrected!
In addition, you can compile restic with debug support by running
2015-11-05 22:09:01 +00:00
`go run build.go -tags debug` and instructing it to create a debug log by
setting the environment variable `DEBUG_LOG` to a file, e.g. like this:
$ export DEBUG_LOG=/tmp/restic-debug.log
$ restic backup ~/work
Please be aware that the debug log file will contain potentially sensitive
things like file and directory names, so please either redact it before
uploading it somewhere or post only the parts that are really relevant.
2015-06-24 17:20:27 +00:00
Development Environment
=======================
2016-02-20 16:24:16 +00:00
For development you need the build tool [`gb`](https://getgb.io), it can be
installed by running the following command:
2015-06-24 17:20:27 +00:00
$ go get github.com/constabulary/gb/...
2015-06-24 17:20:27 +00:00
2016-02-20 16:24:16 +00:00
The repository contains two directories with code: `src/` contains the code
written for restic, whereas `vendor/` contains copies of libraries restic
depends on. The libraries are managed with the `gb vendor` command.
2015-06-24 17:20:27 +00:00
2016-02-20 16:24:16 +00:00
Just clone the repository, `cd` to it and run `gb build` to build the binary:
2015-06-24 17:20:27 +00:00
2016-02-20 16:24:16 +00:00
$ git clone https://github.com/restic/restic
$ cd restic
$ gb build
[...]
$ bin/restic version
restic compiled manually
compiled at unknown time with go1.6
2015-06-24 17:20:27 +00:00
The following commands can be used to run all the tests:
2016-02-20 16:24:16 +00:00
$ gb test
2015-06-24 17:20:27 +00:00
ok github.com/restic/restic 8.174s
[...]
2016-02-20 16:24:16 +00:00
If you want to run your tests on Linux, OpenBSD or FreeBSD, you can use
2017-01-31 09:09:59 +00:00
[vagrant](https://www.vagrantup.com/) with the provided `Vagrantfile` to
2015-07-18 22:05:04 +00:00
quickly set up VMs and run the tests, e.g.:
$ vagrant up freebsd
[...]
$ vagrant ssh freebsd -c 'cd restic/restic; go test -v ./...'
[...]
The default `go` tool can also be used by setting the environment variable
`GOPATH` to the following value while being in the top level directory in the
git repository:
$ export GOPATH=$PWD:$PWD/vendor
The file `.envrc` allows automatic `GOPATH` configuration with
[direnv](https://direnv.net/), inspect the file and then allow automatic
configuration by running `direnv allow`.
2015-05-06 21:18:46 +00:00
Providing Patches
2015-05-06 07:11:07 +00:00
=================
2015-05-06 21:18:46 +00:00
You have fixed an annoying bug or have added a new feature? Very cool! Let's
2015-05-09 15:20:18 +00:00
get it into the project! The workflow we're using is also described on the
2015-05-09 09:11:00 +00:00
[GitHub Flow](https://guides.github.com/introduction/flow/) website, it boils
2015-05-09 15:20:18 +00:00
down to the following steps:
2015-05-09 09:11:00 +00:00
2016-02-20 16:24:16 +00:00
0. If you want to work on something, please add a comment to the issue on
GitHub. For a new feature, please add an issue before starting to work on
it, so that duplicate work is prevented.
2015-05-09 09:11:00 +00:00
1. First we would kindly ask you to fork our project on GitHub if you haven't
done so already.
2016-02-20 16:24:16 +00:00
2015-06-24 17:20:27 +00:00
2. Clone the repository locally and create a new branch. If you are working on
the code itself, please set up the development environment as described in
2016-02-20 16:24:16 +00:00
the previous section.
2015-05-09 09:11:00 +00:00
3. Then commit your changes as fine grained as possible, as smaller patches,
that handle one and only one issue are easier to discuss and merge.
2016-02-20 16:24:16 +00:00
2015-05-09 09:11:00 +00:00
4. Push the new branch with your changes to your fork of the repository.
2016-02-20 16:24:16 +00:00
2015-05-09 09:11:00 +00:00
5. Create a pull request by visiting the GitHub website, it will guide you
through the process.
2016-02-20 16:24:16 +00:00
2015-05-09 09:11:00 +00:00
6. You will receive comments on your code and the feature or bug that they
address. Maybe you need to rework some minor things, in this case push new
commits to the branch you created for the pull request, they will be
automatically added to the pull request.
2016-02-20 16:24:16 +00:00
7. Once your code looks good and passes all the tests, we'll merge it. Thanks
a low for your contribution!
2015-05-06 07:11:07 +00:00
2015-05-09 09:11:00 +00:00
Please provide the patches for each bug or feature in a separate branch and
open up a pull request for each.
The restic project uses the `gofmt` tool for Go source indentation, so please
2015-05-06 21:18:46 +00:00
run
2015-05-06 07:11:07 +00:00
gofmt -w **/*.go
2015-05-06 21:18:46 +00:00
in the project root directory before committing. Installing the script
`fmt-check` from https://github.com/edsrzf/gofmt-git-hook locally as a
pre-commit hook checks formatting before committing automatically, just copy
this script to `.git/hooks/pre-commit`.
2015-05-06 07:11:07 +00:00
For each pull request, several different systems run the integration tests on
Linux, OS X and Windows. We won't merge any code that does not pass all tests
for all systems, so when a tests fails, try to find out what's wrong and fix
it. If you need help on this, please leave a comment in the pull request, and
we'll be glad to assist. Having a PR with failing integration tests is nothing
to be ashamed of. In contrast, that happens regularly for all of us. That's
what the tests are there for.
2015-08-12 18:38:43 +00:00
Git Commits
-----------
I would be good if you could follow the same general style regarding Git
commits as the rest of the project, this makes reviewing code, browsing the
history and triaging bugs much easier.
Git commit messages have a very terse summary in the first line of the commit
message, followed by an empty line, followed by a more verbose description or a
List of changed things. For examples, please refer to the excellent [How to
Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
If you change/add multiple different things that aren't related at all, try to
make several smaller commits. This is much easier to review. Using `git add -p`
allows staging and committing only some changes.
2015-05-06 21:18:46 +00:00
Code Review
2015-05-06 07:11:07 +00:00
===========
2015-05-06 21:18:46 +00:00
The restic project encourages actively reviewing the code, as it will store
2015-05-09 09:11:00 +00:00
your precious data, so it's common practice to receive comments on provided
2015-05-06 21:18:46 +00:00
patches.
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
If you are reviewing other contributor's code please consider the following
when reviewing:
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
* Be nice. Please make the review comment as constructive as possible so all
participants will learn something from your review.
2015-05-06 07:11:07 +00:00
2015-05-06 21:18:46 +00:00
As a contributor you might be asked to rewrite portions of your code to make it
fit better into the upstream sources.