Untangle and clarify the contributing guide (#22169)

* Small typos and clarification in contributing guide

* cross-link contributing guide and issue/pr template

* drop GOPATH mention

* don't include merge commits in PRs

* make high review delays explicit

* explicitly ask for link to current PR in changelog template

* clarify docs changes

* use bug template as authoritative place'

* consolidate development information in 090_participating

Also move issue / PR creation relevant information into contributing.md.

* clarify meaning of assigning to a pull request

* link to minimum go version

* minor typos

* golanci-lint is always applied in full

* add micro summary

* more typo fixes

* always run golangci-lint

* Simplify issue/pr template

* Fix IRC webchat link

* Move security policy to SECURITY.md

* address review comments
This commit is contained in:
Michael Eischer authored and GitHub committed 2026-11-15 17:40:08 +01:00
1 parent c734245fd3
commit 354f6aeed6
9 files changed
+198 -181

No files matched your search

+99 -45
View File
@@ -10,9 +10,65 @@
^ for subsubsections
" for paragraphs
#############
Participating
#############
###########
Development
###########
This section covers how to develop, debug, profile and write tests for restic. For opening
issues and pull requests, see the next section.
************
Contributing
************
Contributions are welcome! More information can be
found in `CONTRIBUTING.md <https://github.com/restic/restic/blob/master/CONTRIBUTING.md>`__.
A document describing the design of restic and the data structures stored on the
back end is contained in :ref:`repository-format`.
If you'd like to start contributing to restic, but don't know exactly
what to do, have a look at this great article by Dave Cheney:
`Suggestions for contributing to an Open Source
project <https://dave.cheney.net/2016/03/12/suggestions-for-contributing-to-an-open-source-project>`__.
***********************
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
<https://github.com/restic/restic/blob/master/go.mod#L3>`__. Clone the repo
and ``cd`` into the directory:
.. code-block:: console
$ git clone https://github.com/restic/restic
$ cd restic
Then use the ``go`` tool to build restic:
.. code-block:: console
$ go run build.go
$ ./restic version
restic 0.19.1-dev (compiled manually) compiled with go1.26.10 on linux/amd64
To create a debug build use:
.. code-block:: console
$ go run build.go -tags debug
You can run all tests with the following command:
.. code-block:: console
$ go test ./...
**********
Debug Logs
@@ -59,6 +115,21 @@ statements originating in functions that match the pattern ``*unlock*``
$ DEBUG_FUNCS=*unlock* restic check
***********
Debug Hangs
***********
If restic gets stuck, you can generate a stacktrace as follows.
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 run restic with the environment variable
``RESTIC_DEBUG_STACKTRACE_SIGINT`` set to ``true`` and press ``Ctrl-C`` to
create a stacktrace.
*********
Debugging
@@ -73,37 +144,37 @@ The program can be built with debug support like this:
This will make the ``restic debug <subcommand>`` available which can be used to
inspect internal data structures.
In addition, this enables profiling flags such as ``--cpu-profile`` and
``--mem-profile`` which can help when investigating performance and memory usage
issues. See ``restic help`` for more details and a few additional
``--...-profile`` flags.
Running restic with profiling enabled generates a ``.pprof`` file such as
``cpu.pprof``. To view a profile in a web browser, first make sure that the
``dot`` command from `Graphviz <https://graphviz.org/>`__ is in the PATH. Then,
run ``go tool pprof -http : cpu.pprof``.
***********************************
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:
************
Contributing
************
.. code-block:: console
Contributions are welcome! 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.
$ restic --cpu-profile . [...]
$ go tool pprof -http localhost:12345 cpu.pprof
More information and a description of the development environment can be
found in `CONTRIBUTING.md <https://github.com/restic/restic/blob/master/CONTRIBUTING.md>`__.
A document describing the design of restic and the data structures stored on the
back end is contained in :ref:`repository-format`.
To analyze a trace profile use ``go tool trace -http=localhost:12345 trace.out``.
If you'd like to start contributing to restic, but don't know exactly
what to do, have a look at this great article by Dave Cheney:
`Suggestions for contributing to an Open Source
project <https://dave.cheney.net/2016/03/12/suggestions-for-contributing-to-an-open-source-project>`__.
A few issues have been tagged with the label ``help wanted``, you can
start looking at `those <https://github.com/restic/restic/labels/help%3A%20wanted>`_.
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 the ``--listen-profile``
option. Then while restic runs you can query and afterwards analyze the heap statistics.
.. code-block:: console
$ restic --listen-profile localhost:12345 [...]
$ curl http://localhost:12345/debug/pprof/heap -o heap.pprof
$ go tool pprof -http localhost:12345 heap.pprof
The memory usage of restic primarily depends on the index size. To get an idea of the
number of tree and data blobs in the repository, you can use the ``restic stats --mode debug`` command.
Setting ``GODEBUG=gctrace=1`` prints garbage-collector runs. For a graphical variant
combine this with `gcvis <https://github.com/davecheney/gcvis>`__.
*************
@@ -229,23 +300,6 @@ Example: this is a typical setup for a backup / find scenario
rtest.Assert(t, len(lines) == 2, "expected one file, found (%v) in repo", len(lines)-1)
********
Security
********
**Important**: If you discover something that you believe to be a
possible critical security problem, please do *not* open a GitHub issue
but send an email directly to alexander@bumpern.de. If possible, please
encrypt your email using the following PGP key
(`0x91A6868BD3F7A907 <https://restic.net/gpg-key-alex.asc>`__):
::
pub 4096R/91A6868BD3F7A907 2014-11-01
Key fingerprint = CF8F 18F2 8445 7597 3F79 D4E1 91A6 868B D3F7 A907
uid Alexander Neumann <alexander@bumpern.de>
sub 4096R/D5FC2ACF4043FDF1 2014-11-01
*************
Compatibility
*************