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