github.com/mckael/restic@v0.8.3/doc/090_participating.rst (about) 1 .. 2 Normally, there are no heading levels assigned to certain characters as the structure is 3 determined from the succession of headings. However, this convention is used in Python’s 4 Style Guide for documenting which you may follow: 5 6 # with overline, for parts 7 * for chapters 8 = for sections 9 - for subsections 10 ^ for subsubsections 11 " for paragraphs 12 13 ############# 14 Participating 15 ############# 16 17 ********* 18 Debugging 19 ********* 20 21 The program can be built with debug support like this: 22 23 .. code-block:: console 24 25 $ go run build.go -tags debug 26 27 Afterwards, extensive debug messages are written to the file in 28 environment variable ``DEBUG_LOG``, e.g.: 29 30 .. code-block:: console 31 32 $ DEBUG_LOG=/tmp/restic-debug.log restic backup ~/work 33 34 If you suspect that there is a bug, you can have a look at the debug 35 log. Please be aware that the debug log might contain sensitive 36 information such as file and directory names. 37 38 The debug log will always contain all log messages restic generates. You 39 can also instruct restic to print some or all debug messages to stderr. 40 These can also be limited to e.g. a list of source files or a list of 41 patterns for function names. The patterns are globbing patterns (see the 42 documentation for `path.Glob <https://golang.org/pkg/path/#Glob>`__), multiple 43 patterns are separated by commas. Patterns are case sensitive. 44 45 Printing all log messages to the console can be achieved by setting the 46 file filter to ``*``: 47 48 .. code-block:: console 49 50 $ DEBUG_FILES=* restic check 51 52 If you want restic to just print all debug log messages from the files 53 ``main.go`` and ``lock.go``, set the environment variable 54 ``DEBUG_FILES`` like this: 55 56 .. code-block:: console 57 58 $ DEBUG_FILES=main.go,lock.go restic check 59 60 The following command line instructs restic to only print debug 61 statements originating in functions that match the pattern ``*unlock*`` 62 (case sensitive): 63 64 .. code-block:: console 65 66 $ DEBUG_FUNCS=*unlock* restic check 67 68 69 ************ 70 Contributing 71 ************ 72 73 Contributions are welcome! Please **open an issue first** (or add a 74 comment to an existing issue) if you plan to work on any code or add a 75 new feature. This way, duplicate work is prevented and we can discuss 76 your ideas and design first. 77 78 More information and a description of the development environment can be 79 found in `CONTRIBUTING.md <https://github.com/restic/restic/blob/master/CONTRIBUTING.md>`__. 80 A document describing the design of restic and the data structures stored on the 81 back end is contained in `Design <https://restic.readthedocs.io/en/latest/design.html>`__. 82 83 If you'd like to start contributing to restic, but don't know exactly 84 what do to, have a look at this great article by Dave Cheney: 85 `Suggestions for contributing to an Open Source 86 project <http://dave.cheney.net/2016/03/12/suggestions-for-contributing-to-an-open-source-project>`__ 87 A few issues have been tagged with the label ``help wanted``, you can 88 start looking at those: 89 https://github.com/restic/restic/labels/help%20wanted 90 91 ******** 92 Security 93 ******** 94 95 **Important**: If you discover something that you believe to be a 96 possible critical security problem, please do *not* open a GitHub issue 97 but send an email directly to alexander@bumpern.de. If possible, please 98 encrypt your email using the following PGP key 99 (`0x91A6868BD3F7A907 <https://pgp.mit.edu/pks/lookup?op=get&search=0xCF8F18F2844575973F79D4E191A6868BD3F7A907>`__): 100 101 :: 102 103 pub 4096R/91A6868BD3F7A907 2014-11-01 104 Key fingerprint = CF8F 18F2 8445 7597 3F79 D4E1 91A6 868B D3F7 A907 105 uid Alexander Neumann <alexander@bumpern.de> 106 sub 4096R/D5FC2ACF4043FDF1 2014-11-01 107 108 ************* 109 Compatibility 110 ************* 111 112 Backward compatibility for backups is important so that our users are 113 always able to restore saved data. Therefore restic follows `Semantic 114 Versioning <http://semver.org>`__ to clearly define which versions are 115 compatible. The repository and data structures contained therein are 116 considered the "Public API" in the sense of Semantic Versioning. This 117 goes for all released versions of restic, this may not be the case for 118 the master branch. 119 120 We guarantee backward compatibility of all repositories within one major 121 version; as long as we do not increment the major version, data can be 122 read and restored. We strive to be fully backward compatible to all 123 prior versions. 124 125 ********************** 126 Building documentation 127 ********************** 128 129 The restic documentation is built with `Sphinx <http://sphinx-doc.org>`__, 130 therefore building it locally requires a recent Python version and requirements listed in ``doc/requirements.txt``. 131 This example will guide you through the process using `virtualenv <https://virtualenv.pypa.io>`__: 132 133 :: 134 135 $ virtualenv venv # create virtual python environment 136 $ source venv/bin/activate # activate the virtual environment 137 $ cd doc 138 $ pip install -r requirements.txt # install dependencies 139 $ make html # build html documentation 140 $ # open _build/html/index.html with your favorite browser