From c7e6ca20e461c8461f22dca151b543a128e9d8fd Mon Sep 17 00:00:00 2001 From: Markus Unterwaditzer Date: Wed, 2 Mar 2016 23:27:48 +0100 Subject: [PATCH] Add packaging guidelines --- MANIFEST.in | 2 ++ Makefile | 15 +++-------- docs-requirements.txt | 2 ++ docs/index.rst | 1 + docs/packaging.rst | 60 +++++++++++++++++++++++++++++++++++++++++++ setup.py | 2 +- test-requirements.txt | 5 ++++ 7 files changed, 74 insertions(+), 13 deletions(-) create mode 100644 docs-requirements.txt create mode 100644 docs/packaging.rst create mode 100644 test-requirements.txt diff --git a/MANIFEST.in b/MANIFEST.in index 24ea06d..4faef4e 100644 --- a/MANIFEST.in +++ b/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 * diff --git a/Makefile b/Makefile index 2f2ea0d..4da8219 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,4 @@ -# Packagers who want to run the testsuite against an installed vdirsyncer: -# -# - 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. +# See the documentation on how to run the tests. 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 diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000..8213302 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,2 @@ +sphinx +sphinx_rtd_theme diff --git a/docs/index.rst b/docs/index.rst index 5f72d14..50aa337 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ Table of Contents problems vdir contributing + packaging contact changelog license diff --git a/docs/packaging.rst b/docs/packaging.rst new file mode 100644 index 0000000..77663ca --- /dev/null +++ b/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 +`_, 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 +`_ 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. diff --git a/setup.py b/setup.py index f721e18..6831bad 100644 --- a/setup.py +++ b/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'] diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..85cb644 --- /dev/null +++ b/test-requirements.txt @@ -0,0 +1,5 @@ +hypothesis>=3 +pytest +pytest-localserver +pytest-subtesthack +pytest-xprocess