Add packaging guidelines

MANIFEST.in

@@ -3,6 +3,8 @@ include CHANGELOG.rst
 include LICENSE
 include config.example
 include Makefile
+include test-requirements.txt
+include docs-requirements.txt
 
 recursive-include docs *
 recursive-include tests *

Makefile

@@ -1,11 +1,4 @@
-# Packagers who want to run the testsuite against an installed vdirsyncer:
+# See the documentation on how to run the tests.
-#
-# - Create a virtualenv
-# - Somehow link your installation of vdirsyncer into the virtualenv, e.g. by
-#   using --system-site-packages when creating the virtualenv
-# - Inside the virtualenv: `make install-test test`
-#
-# The `install-test` target requires internet access.
 
 export DAV_SERVER := skip
 export REMOTESTORAGE_SERVER := skip
@@ -28,14 +21,12 @@ install-servers:
 
 install-test: install-servers
 	(python --version | grep -vq 'Python 3.3') || pip install enum34
+	pip install -r test-requirements.txt
 	set -xe && if [ "$$REQUIREMENTS" = "devel" ]; then \
 		pip install -U --force-reinstall \
 			git+https://github.com/DRMacIver/hypothesis \
 			git+https://github.com/pytest-dev/pytest; \
-	else \
-		pip install pytest hypothesis; \
 	fi
-	pip install pytest-xprocess pytest-localserver pytest-subtesthack
 	[ $(TRAVIS) != "true" ] || pip install coverage codecov
 
 test:
@@ -62,7 +53,7 @@ travis-conf:
 	python3 scripts/make_travisconf.py > .travis.yml
 
 install-docs:
-	pip install sphinx sphinx_rtd_theme
+	pip install -r docs-requirements.txt
 
 docs:
 	cd docs && make html

docs-requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/index.rst

@@ -29,6 +29,7 @@ Table of Contents
    problems
    vdir
    contributing
+   packaging
    contact
    changelog
    license

docs/packaging.rst

@@ -0,0 +1,60 @@
+====================
+Packaging guidelines
+====================
+
+Thank you very much for packaging vdirsyncer! The following guidelines should
+help you to avoid some common pitfalls.
+
+While they are called guidelines and therefore theoretically not mandatory, if
+you consider going a different direction, please first open an issue or contact
+me otherwise instead of just going ahead. These guidelines exist for my own
+convenience too.
+
+Obtaining the source code
+=========================
+
+The main distribution channel is `PyPI
+<https://pypi.python.org/pypi/vdirsyncer>`_, and source tarballs can be
+obtained there. Do not use the ones from GitHub: Their tarballs contain useless
+junk and are more of a distraction than anything else.
+
+I give each release a tag in the git repo. If you want to get notified of new
+releases, `GitHub's feed
+<https://github.com/untitaker/vdirsyncer/releases.atom>`_ is a good way.
+
+Dependency versions
+===================
+
+It is strongly discouraged to package vdirsyncer as a Python 2 application.
+Future releases will only work on Python 3.3 and newer versions.
+
+As with most Python packages, ``setup.py`` denotes the runtime dependencies of
+vdirsyncer. It also contains lower-bound versions of each dependency. Older
+versions will be rejected by the testsuite.
+
+Testing
+=======
+
+Everything testing-related goes through the ``Makefile`` in the root of the
+repository or PyPI package. Trying to e.g. run ``py.test`` directly will
+require a lot of environment variables to be set (for configuration) and you
+probably don't want to deal with that.
+
+You can install the testing dependencies with ``make test-install``. You
+probably don't want this since it will use pip to download the dependencies.
+Alternatively you can find the testing dependencies in
+``test-requirements.txt``, again with lower-bound version requirements.
+
+You also have to have vdirsyncer fully installed at this point. Merely
+``cd``-ing into the tarball will not be sufficient.
+
+Running the tests happens with ``make test``.
+
+Documentation
+=============
+
+You can find a list of dependencies in ``docs-requirements.txt``.
+
+Change into the ``docs/`` directory and build whatever format you want. That
+said, I only take care of the HTML docs' formatting -- other targets (such as
+the generated manpage) may look like garbage.

setup.py

@@ -50,7 +50,7 @@ setup(
         ),
         # https://github.com/sigmavirus24/requests-toolbelt/pull/28
         'requests_toolbelt >=0.5.0',
-        'atomicwrites'
+        'atomicwrites>=0.1.6'
     ],
     extras_require={
         'remotestorage': ['requests-oauthlib']

test-requirements.txt

@@ -0,0 +1,5 @@
+hypothesis>=3
+pytest
+pytest-localserver
+pytest-subtesthack
+pytest-xprocess