1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
============================
Contributing to this project
============================
.. note::
- Please read :doc:`contact` for questions and support requests.
- All participants must follow the `pimutils Code of Conduct
<http://pimutils.org/coc>`_.
The issue tracker
=================
We use `GitHub issues <https://github.com/pimutils/vdirsyncer/issues>`_ for
organizing bug reports and feature requests.
The following `labels <https://github.com/pimutils/vdirsyncer/labels>`_ are of
interest:
* "Planning" is for issues that are still undecided, but where at least some
discussion exists.
* "Blocked" is for issues that can't be worked on at the moment because some
other unsolved problem exists. This problem may be a bug in some software
dependency, for instance.
* "Ready" contains issues that are ready to work on.
If you just want to get started with contributing, the "ready" issues are an
option. Issues that are still in "Planning" are also an option, but require
more upfront thinking and may turn out to be impossible to solve, or at least
harder than anticipated. On the flip side those tend to be the more interesting
issues as well, depending on how one looks at it.
All of those labels are also available as a kanban board on `waffle.io
<https://waffle.io/pimutils/vdirsyncer>`_. It is really just an alternative
overview over all issues, but might be easier to comprehend.
Feel free to :doc:`contact <contact>` me or comment on the relevant issues for
further information.
Reporting bugs
--------------
* Make sure your problem isn't already listed in :doc:`problems`.
* Make sure you have the absolutely latest version of vdirsyncer. For users of
some Linux distributions such as Debian or Fedora this may not be the version
that your distro offers. In those cases please file a bug against the distro
package, not against upstream vdirsyncer.
* Use ``--verbosity=DEBUG`` when including output from vdirsyncer.
Suggesting features
-------------------
If you're suggesting a feature, keep in mind that vdirsyncer tries not to be a
full calendar or contacts client, but rather just the piece of software that
synchronizes all the data. :doc:`Take a look at the documentation for software
working with vdirsyncer <tutorials/index>`.
Submitting patches, pull requests
=================================
* **Discuss everything in the issue tracker first** (or contact me somehow
else) before implementing it.
* Make sure the tests pass. See below for running them.
* But not because you wrote too few tests.
* Add yourself to ``AUTHORS.rst``, and add a note to ``CHANGELOG.rst`` too.
Running tests, how to set up your development environment
---------------------------------------------------------
For many patches, it might suffice to just let CI run the tests. However,
CI is slow, so you might want to run them locally too. For this, set up a
virtualenv_ and run this inside of it::
# Install development dependencies, including:
# - vdirsyncer from the repo into the virtualenv
# - stylecheckers (ruff) and code formatters (black)
make install-dev
# Install git commit hook for some extra linting and checking
pre-commit install
Then you can run::
pytest # The normal testsuite
pre-commit run --all # Run all linters (which also run via pre-commit)
make -C docs html # Build the HTML docs, output is at docs/_build/html/
make -C docs linkcheck # Check docs for any broken links
The ``Makefile`` has a lot of options that allow you to control which tests are
run, and which servers are tested. Take a look at its code where they are all
initialized and documented.
To tests against a specific DAV server, use ``DAV_SERVER``::
make DAV_SERVER=xandikos test
The server will be initialised in a docker container and terminated at the end
of the test suite.
If you have any questions, feel free to open issues about it.
Structure of the testsuite
--------------------------
Within ``tests/``, there are three main folders:
- ``system`` contains system- and also integration tests. A rough rule is: If
the test is using temporary files, put it here.
- ``unit``, where each testcase tests a single class or function.
- ``storage`` runs a generic storage testsuite against all storages.
The reason for this separation is: We are planning to generate separate
coverage reports for each of those testsuites. Ideally ``unit`` would generate
palatable coverage of the entire codebase *on its own*, and the *combination*
of ``system`` and ``storage`` as well.
.. _virtualenv: http://virtualenv.readthedocs.io/
|
