mirror
/
restic
mirror of https://github.com/restic/restic.git
1
0
Fork 0
Code Issues Releases Wiki Activity
restic/doc/090_participating.rst

149 lines
5.2 KiB
ReStructuredText
Raw Normal View History

doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
..
Normally, there are no heading levels assigned to certain characters as the structure is
determined from the succession of headings. However, this convention is used in Python’s
Style Guide for documenting which you may follow:
# with overline, for parts
* for chapters
= for sections
- for subsections
^ for subsubsections
" for paragraphs
#############
Participating
#############
update documentation to reflect DEBUG_LOG for release builds
2022-07-16 20:45:41 +00:00
**********
Debug Logs
**********
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
update documentation to reflect DEBUG_LOG for release builds
2022-07-16 20:45:41 +00:00
Set the environment variable ``DEBUG_LOG`` to let restic write extensive debug
messages to the specified filed, e.g.:
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
.. code-block:: console
$ DEBUG_LOG=/tmp/restic-debug.log restic backup ~/work
If you suspect that there is a bug, you can have a look at the debug
log. Please be aware that the debug log might contain sensitive
information such as file and directory names.
The debug log will always contain all log messages restic generates. You
can also instruct restic to print some or all debug messages to stderr.
These can also be limited to e.g. a list of source files or a list of
patterns for function names. The patterns are globbing patterns (see the
doc: Fix some links, focus less on implementation details The godoc for filepath.Match has the syntax, which is what is important for writing patterns. Use pkg.go.dev instead of golang.org/pkg. For #4245. Not all links fixed yet.
2023-03-12 23:11:22 +00:00
documentation for `filepath.Match <https://pkg.go.dev/path/filepath#Match>`__).
Multiple patterns are separated by commas. Patterns are case sensitive.
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
Printing all log messages to the console can be achieved by setting the
file filter to ``*``:
.. code-block:: console
$ DEBUG_FILES=* restic check
If you want restic to just print all debug log messages from the files
``main.go`` and ``lock.go``, set the environment variable
``DEBUG_FILES`` like this:
.. code-block:: console
$ DEBUG_FILES=main.go,lock.go restic check
The following command line instructs restic to only print debug
statements originating in functions that match the pattern ``*unlock*``
(case sensitive):
.. code-block:: console
$ DEBUG_FUNCS=*unlock* restic check
update documentation to reflect DEBUG_LOG for release builds
2022-07-16 20:45:41 +00:00
*********
Debugging
*********
The program can be built with debug support like this:
.. code-block:: console
$ go run build.go -tags debug
This will make the ``restic debug <subcommand>`` available which can be used to
inspect internal data structures. In addition, this enables profiling support
which can help with investigation performance and memory usage issues.
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
************
Contributing
************
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
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.
More information and a description of the development environment can be
Fix link to CONTRIBUTING.md
2017-06-07 20:44:49 +00:00
found in `CONTRIBUTING.md <https://github.com/restic/restic/blob/master/CONTRIBUTING.md>`__.
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
A document describing the design of restic and the data structures stored on the
back end is contained in `Design <https://restic.readthedocs.io/en/latest/design.html>`__.
If you'd like to start contributing to restic, but don't know exactly
what do to, have a look at this great article by Dave Cheney:
`Suggestions for contributing to an Open Source
docs: Fix link to "help wanted" issues
2021-11-16 00:03:34 +00:00
project <https://dave.cheney.net/2016/03/12/suggestions-for-contributing-to-an-open-source-project>`__.
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
A few issues have been tagged with the label ``help wanted``, you can
docs: Fix link to "help wanted" issues
2021-11-16 00:03:34 +00:00
start looking at `those <https://github.com/restic/restic/labels/help%3A%20wanted>`_.
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
********
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
Security
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
********
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
**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://pgp.mit.edu/pks/lookup?op=get&search=0xCF8F18F2844575973F79D4E191A6868BD3F7A907>`__):
::
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
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
*************
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
Compatibility
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
*************
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
Backward compatibility for backups is important so that our users are
always able to restore saved data. Therefore restic follows `Semantic
Prefer https:// links in the documentation All the changed urls are available by way of https://. Most of them already redirect.
2018-12-29 14:55:25 +00:00
Versioning <https://semver.org>`__ to clearly define which versions are
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
compatible. The repository and data structures contained therein are
considered the "Public API" in the sense of Semantic Versioning. This
goes for all released versions of restic, this may not be the case for
the master branch.
We guarantee backward compatibility of all repositories within one major
version; as long as we do not increment the major version, data can be
read and restored. We strive to be fully backward compatible to all
prior versions.
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
**********************
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
Building documentation
doc: Refactors the documentation This commit refactors the documentation according to my proposal in #1273 and the discussion I had with fd0 on IRC. The bits from the manual that I could not immediately put into the new structure are contained in manual_rest.rst Anything else is still there, nothing has been deleted. I changed the heading markup to follow the convention used in Python’s Style Guide for documentation, this convention is explained in a comment at the top of every file. I also added a paragraph on installing restic on Debian.
2017-09-30 20:01:19 +00:00
**********************
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
Prefer https:// links in the documentation All the changed urls are available by way of https://. Most of them already redirect.
2018-12-29 14:55:25 +00:00
The restic documentation is built with `Sphinx <https://www.sphinx-doc.org>`__,
Documentation: Refactor and switch to Sphinx * convert documentation to reStructuredText * switch from mkdocs to sphinx * rewrite README.md (now .rst) to include less information and be more attractive
2017-04-17 18:53:38 +00:00
therefore building it locally requires a recent Python version and requirements listed in ``doc/requirements.txt``.
This example will guide you through the process using `virtualenv <https://virtualenv.pypa.io>`__:
::
$ virtualenv venv # create virtual python environment
$ source venv/bin/activate # activate the virtual environment
$ cd doc
$ pip install -r requirements.txt # install dependencies
$ make html # build html documentation
$ # open _build/html/index.html with your favorite browser