mirror of
https://github.com/restic/restic.git
synced 2024-12-23 16:26:11 +00:00
ae9683336d
Opening an issue for a small bugfix is usually not useful. It primarily adds overhead.
235 lines
10 KiB
Markdown
235 lines
10 KiB
Markdown
This document describes the way you can contribute to the restic project.
|
|
|
|
Ways to Help Out
|
|
================
|
|
|
|
Thank you for your contribution! Please **open an issue first** (or add a
|
|
comment to an existing issue) if you plan to work on any code or add a new
|
|
feature. This way, duplicate work is prevented and we can discuss your ideas
|
|
and design first. Small bugfixes are an exception to this rule, just open a
|
|
pull request in this case.
|
|
|
|
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.
|
|
|
|
The restic project uses the GitHub infrastructure (see the
|
|
[project page](https://github.com/restic/restic)) for all related discussions
|
|
as well as the [forum](https://forum.restic.net/) and the `#restic` channel
|
|
on [irc.libera.chat](https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:6697/#restic).
|
|
|
|
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/help%3A%20minor%20complexity)
|
|
or [good first issue](https://github.com/restic/restic/labels/help%3A%20good%20first%20issue).
|
|
If you are already a bit experienced with the restic internals, take a look
|
|
at the issues tagged as [help wanted](https://github.com/restic/restic/labels/help%3A%20wanted).
|
|
|
|
|
|
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?
|
|
|
|
Remember, the easier it is for us to reproduce the bug, the earlier it will be
|
|
corrected!
|
|
|
|
In addition, you can instruct restic 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.
|
|
|
|
If restic gets stuck, please also include a stacktrace in the description.
|
|
On non-Windows systems, you can send a SIGQUIT signal to restic or press
|
|
`Ctrl-\` to achieve the same result. This causes restic to print a stacktrace
|
|
and then exit immediately. This will not damage your repository, however,
|
|
it might be necessary to manually clean up stale lock files using
|
|
`restic unlock`.
|
|
|
|
On Windows, please set the environment variable `RESTIC_DEBUG_STACKTRACE_SIGINT`
|
|
to `true` and press `Ctrl-C` to create a stacktrace.
|
|
|
|
If you think restic uses too much memory or a too large cache directory, then
|
|
please include the output of `restic stats --mode debug`.
|
|
|
|
|
|
Development Environment
|
|
=======================
|
|
|
|
The repository contains the code written for restic in the directories
|
|
`cmd/` and `internal/`.
|
|
|
|
Make sure you have the minimum required Go version installed. Clone the repo
|
|
(without having `$GOPATH` set) and `cd` into the directory:
|
|
|
|
$ unset GOPATH
|
|
$ git clone https://github.com/restic/restic
|
|
$ cd restic
|
|
|
|
Then use the `go` tool to build restic:
|
|
|
|
$ go build ./cmd/restic
|
|
$ ./restic version
|
|
restic 0.14.0-dev (compiled manually) compiled with go1.19 on linux/amd64
|
|
|
|
To create a debug build use:
|
|
|
|
$ go build -tags debug ./cmd/restic
|
|
|
|
You can run all tests with the following command:
|
|
|
|
$ go test ./...
|
|
|
|
|
|
Performance and Memory Usage Issues
|
|
===================================
|
|
|
|
Debug builds of restic support the `--block-profile`, `--cpu-profile`,
|
|
`--mem-profile`, and `--trace-profile` options which collect performance data
|
|
that later on can be analyzed using the go tools:
|
|
|
|
$ restic --cpu-profile . [...]
|
|
$ go tool pprof -http localhost:12345 cpu.pprof
|
|
|
|
To analyze a trace profile use `go tool trace -http=localhost:12345 trace.out`.
|
|
|
|
As the memory usage of restic changes over time, it may be useful to capture a
|
|
snapshot of the current heap. This is possible using then `--listen-profile`
|
|
option. Then while restic runs you can query and afterwards analyze the heap statistics.
|
|
|
|
$ restic --listen-profile localhost:12345 [...]
|
|
$ curl http://localhost:12345/debug/pprof/heap -o heap.pprof
|
|
$ go tool pprof -http localhost:12345 heap.pprof
|
|
|
|
Further useful tools are setting the environment variable `GODEBUG=gctrace=1`,
|
|
which provides information about garbage collector runs. For a graphical variant
|
|
combine this with gcvis.
|
|
|
|
|
|
Providing Patches
|
|
=================
|
|
|
|
You have fixed an annoying bug or have added a new feature? Very cool! Let's
|
|
get it into the project! The workflow we're using is also described on the
|
|
[GitHub Flow](https://guides.github.com/introduction/flow/) website, it boils
|
|
down to the following steps:
|
|
|
|
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.
|
|
|
|
1. Next, fork our project on GitHub if you haven't done so already.
|
|
|
|
2. Clone your fork of the repository locally and **create a new branch** for
|
|
your changes. If you are working on the code itself, please set up the
|
|
development environment as described in the previous section.
|
|
|
|
3. Commit your changes to the new branch as fine grained as possible, as
|
|
smaller patches, for individual changes, are easier to discuss and merge.
|
|
|
|
4. Push the new branch with your changes to your fork of the repository.
|
|
|
|
5. Create a pull request by visiting the GitHub website, it will guide you
|
|
through the process. Please [allow edits from maintainers](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
|
|
|
|
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 (or amend the
|
|
existing commit, use common sense to decide which is better), they will be
|
|
automatically added to the pull request.
|
|
|
|
7. If your pull request changes anything that users should be aware of
|
|
(a bugfix, a new feature, ...) please add an entry as a new file in
|
|
`changelog/unreleased` including the issue number in the filename (e.g.
|
|
`issue-8756`). Use the template in `changelog/TEMPLATE` for the content.
|
|
It will be used in the announcement of the next stable release. While
|
|
writing, ask yourself: If I were the user, what would I need to be aware
|
|
of with this change?
|
|
|
|
8. Do not edit the man pages under `doc/man` or `doc/manual_rest.rst` -
|
|
these are autogenerated before new releases.
|
|
|
|
9. Once your code looks good and passes all the tests, we'll merge it. Thanks
|
|
a lot for your contribution!
|
|
|
|
Please provide the patches for each bug or feature in a separate branch and
|
|
open up a pull request for each, as this simplifies discussion and merging.
|
|
|
|
The restic project uses the `gofmt` tool for Go source indentation, so please
|
|
run
|
|
|
|
gofmt -w **/*.go
|
|
|
|
in the project root directory before committing. For each Pull Request, the
|
|
formatting is tested with `gofmt` for the latest stable version of Go.
|
|
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`.
|
|
|
|
The project is using the program
|
|
[`golangci-lint`](https://github.com/golangci/golangci-lint) to run a list of
|
|
linters and checkers. It will be run on the code when you submit a PR. In order
|
|
to check your code beforehand, you can run `golangci-lint run` manually.
|
|
Eventually, we will enable `golangci-lint` for the whole code base. For now,
|
|
you can ignore warnings printed for lines you did not modify, those will be
|
|
ignored by the CI.
|
|
|
|
For each pull request, several different systems run the integration tests on
|
|
Linux, macOS 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.
|
|
|
|
Git Commits
|
|
-----------
|
|
|
|
It 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](https://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.
|
|
|
|
Code Review
|
|
===========
|
|
|
|
The restic project encourages actively reviewing the code, as it will store
|
|
your precious data, so it's common practice to receive comments on provided
|
|
patches.
|
|
|
|
If you are reviewing other contributor's code please consider the following
|
|
when reviewing:
|
|
|
|
* Be nice. Please make the review comment as constructive as possible so all
|
|
participants will learn something from your review.
|
|
|
|
As a contributor you might be asked to rewrite portions of your code to make it
|
|
fit better into the upstream sources.
|