Contributing to this project
****************************

Note:

  * Please read Support and Contact for questions and support
    requests.

  * All participants must follow the pimutils Code of Conduct.


The issue tracker
=================

We use GitHub issues for organizing bug reports and feature requests.

The following 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.
It is really just an alternative overview over all issues, but might
be easier to comprehend.

Feel free to contact me or comment on the relevant issues for further
information.


Reporting bugs
--------------

* Make sure your problem isn't already listed in Known 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. Take a look at the
documentation for software working with vdirsyncer.


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
   #  - style checks and formatting (ruff)
   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.
