use CalVer, docs updates, cleanups

.gitignore

@@ -11,7 +11,6 @@ __pycache__/
 env/
 build/
 develop-eggs/
-dist/
 downloads/
 eggs/
 .eggs/

MANIFEST.in

@@ -1,5 +1,7 @@
 recursive-include License *
 recursive-include aioprometheus *.py
+recursive-include tests *.py
 include proto/prometheus_metrics.proto
 include requirements.txt
+include Makefile
 prune pyrobuf

Makefile

@@ -72,7 +72,7 @@ docs: coverage
 
 
 # help: sdist                          - create a source distribution package
-dist:
+dist: clean
 	@python setup.py sdist
 
 

README.rst

@@ -1,17 +1,19 @@
 .. image:: https://travis-ci.org/claws/aioprometheus.svg?branch=master
     :target: https://travis-ci.org/claws/aioprometheus
 
-.. image:: https://img.shields.io/pypi/status/aioprometheus.svg?maxAge=2592000?style=plastic
+.. image:: https://img.shields.io/pypi/v/aioprometheus.svg
     :target: https://pypi.python.org/pypi/aioprometheus
 
+
 aioprometheus
 =============
 
 `aioprometheus` is a Prometheus Python client library for asyncio-based
 applications. It provides metrics collection and serving capabilities,
 supports multiple data formats and pushing metrics to a gateway.
 
-The project documentation can be found on `ReadTheDocs <http://aioprometheus.readthedocs.org/>`_.
+The project documentation can be found on
+`ReadTheDocs <http://aioprometheus.readthedocs.org/>`_.
 
 
 Install

aioprometheus/__init__.py

@@ -5,3 +5,5 @@
 from .pusher import Pusher
 from .registry import Registry, CollectorRegistry
 from .service import Service
+
+__version__ = "16.06.01"

dist/.gitignore

@@ -0,0 +1,3 @@
+aioprometheus-*/
+aioprometheus-*.tar.gz
+test_venv/

dist/test.bash

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+if [ -z "$1" ]; then
+  echo "usage: $0 aioprometheus-YY.MM.MICRO.tar.gz"
+  exit
+fi
+
+RELEASE_ARCHIVE="$1"
+RELEASE_DIR=`echo $RELEASE_ARCHIVE | sed -e "s/\.tar\.gz//g"`
+
+echo "Release archive: $RELEASE_ARCHIVE"
+echo "Release directory: $RELEASE_DIR"
+
+echo "Removing any old artefacts"
+rm -rf $RELEASE_DIR
+rm -rf test_venv
+
+echo "Creating test virtual environment"
+python -m venv test_venv
+
+echo "Entering test virtual environment"
+source test_venv/bin/activate
+
+echo "Upgrading pip"
+pip install pip --upgrade
+
+echo "Installing $RELEASE_ARCHIVE"
+tar xf $RELEASE_ARCHIVE
+cd $RELEASE_DIR
+pip install .
+
+echo "Running tests"
+make test
+cd ..
+
+echo "Exiting test virtual environment"
+deactivate

docs/.gitignore

@@ -1,3 +1,4 @@
 _build
 api/aioprometheus*.rst
+api/modules*.rst
 coverage

docs/api/index.rst

@@ -7,4 +7,4 @@ this part of the documentation is for you.
 
 .. toctree::
 
-   aioprometheus.rst
+   modules.rst

docs/conf.py

@@ -24,11 +24,16 @@
 sys.path.insert(0, os.path.abspath('..'))
 
 
-with open(os.path.abspath('../setup.py'), 'rt') as f:
-    _m = re.search(r'''version=(?P<q>'|")(?P<ver>[\d\.]+)(?P=q)''', f.read())
-    if not _m:
-        raise RuntimeError("Can't read version from setup.py")
-    version = _m.group('ver')
+init_file = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)), 'aioprometheus', '__init__.py')
+with open(init_file, 'rt') as f:
+    m = re.search(
+        r'''^__version__\W*=\W*['\"](\d\d\.\d\d\.\d+)['\"]''', f.read(), re.M)
+    if not m:
+        raise RuntimeError(
+            'Cannot find __version__ in aioprometheus/__init__.py')
+    version = m.group(1)
+
 
 # -- General configuration ------------------------------------------------
 

docs/dev/index.rst

@@ -73,8 +73,8 @@ Install aioprometheus
 ---------------------
 
 Use ``pip`` to perform a development install of `aioprometheus`. This installs
-the package in a way that allows you to edit the code after its installed and
-have the changes take effect immediately.
+the package in a way that allows you to edit the code after its installed so
+that any changes take effect immediately.
 
 .. code-block:: console
 
@@ -107,6 +107,12 @@ package too.
     $ python -m unittest test_negotiate
 
 
+Coverage
+--------
+
+The test code coverage report can be found `here <../coverage/coverage.html>`_
+
+
 Documentation
 -------------
 
@@ -130,6 +136,72 @@ Then open a browser to the `docs <http://localhost:8000/_build/html/index.html>`
 content.
 
 
+.. _version-label:
+
+Version
+-------
+
+`aioprometheus` uses a three segment `CalVer <http://calver.org/>`_ versioning
+scheme comprising a short year, a zero padded month and then a micro version.
+The ``YY.MM`` part of the version are treated similarly to a SemVer major
+version. So when backwards incompatible or major functional changes occur the
+``YY.MM`` will be rolled up. For all other minor changes only the micro part
+will be incremented.
+
+
+Release Process
+---------------
+
+The following steps are used to make a new software release:
+
+- Update the version label in ``__init__.py``. It must comply with the
+  :ref:`version-label` scheme
+- Create the distribution
+
+  .. code-block:: console
+
+      make dist
+
+- Test distribution in ``dist/`` directory. This involves creating a virtual
+  environment, installing the source distribution in it and running the tests.
+  These steps have been captured for convenience in the ``dist/test.bash``
+  helper script. The script takes the distribution archive as its only
+  argument.
+
+  .. code-block:: console
+
+      cd dist
+      ./test.bash aioprometheus-16.06.01.tar.gz
+      cd ..
+
+- Build the docs and check for any errors.
+
+  .. code-block:: console
+
+      make docs
+
+- Upload to PyPI using
+
+  .. code-block:: console
+
+      python setup.py upload
+
+- Create and push a repo tag to Github.
+
+  .. code-block:: console
+
+      git tag YY.MM.MICRO -m "A meaningful release tag comment"
+      git tag  # check release tag is in list
+      git push --tags origin master
+
+  - Github will create a release tarball at:
+
+    ::
+
+        https://github.com/{username}/{repo}/tarball/{tag}.tar.gz
+
+
+
 Internals
 ---------
 
@@ -139,7 +211,7 @@ implementation of the Protocol Buffers serialisation library. Pyrobuf does
 not repuire `protoc`.
 
 Extension modules created by ``pyrobuf`` are installed as separate packages.
-When `aioprometheus` is installed you actually get two packages installed;
+So, when `aioprometheus` is installed you actually get two packages installed;
 ``aioprometheus`` and ``prometheus_metrics_proto``.
 
 The Protocol Buffer specification used by `aioprometheus` was obtained from the

docs/index.rst

@@ -1,13 +1,14 @@
 .. image:: https://travis-ci.org/claws/aioprometheus.svg?branch=master
     :target: https://travis-ci.org/claws/aioprometheus
 
-.. image:: https://img.shields.io/pypi/status/aioprometheus.svg?maxAge=2592000?style=plastic
+.. image:: https://img.shields.io/pypi/v/aioprometheus.svg
     :target: https://pypi.python.org/pypi/aioprometheus
 
 aioprometheus
 =============
 
-`aioprometheus` provides asyncio based applications with a metrics
+`aioprometheus` is a Prometheus Python client library for asyncio-based
+applications. It provides asyncio based applications with a metrics
 collection and serving capability for use with the
 `Prometheus <https://prometheus.io/>`_ monitoring and alerting system.
 It supports multiple data formats and pushing metrics to a gateway.
@@ -17,8 +18,7 @@ The project source code can be found `here <https://github.com/claws/aiopromethe
 .. warning::
 
     While this project is mostly in a usable state it is still very early in
-    development. There is no backwards compatibility guarantees until the
-    1.0 release occurs.
+    development. There are no backwards compatibility guarantees yet.
 
 `aioprometheus` originates from the (now deprecated)
 `prometheus python <https://github.com/slok/prometheus-python>`_ package.

setup.py

@@ -1,4 +1,7 @@
 
+import os
+import re
+
 from pip.req import parse_requirements
 from pip.download import PipSession
 from setuptools import setup
@@ -8,26 +11,41 @@
 requires = [str(ir.req) for ir in install_reqs]
 
 
+def read_version():
+    regexp = re.compile(r"^__version__\W*=\W*['\"](\d\d\.\d\d\.\d+)['\"]")
+    init_file = os.path.join(
+        os.path.dirname(__file__), 'aioprometheus', '__init__.py')
+    with open(init_file) as f:
+        for line in f:
+            match = regexp.match(line)
+            if match:
+                return match.group(1)
+        else:
+            raise RuntimeError(
+                'Cannot find __version__ in aioprometheus/__init__.py')
+
+version = read_version()
+
+
 if __name__ == "__main__":
 
     setup(
         name="aioprometheus",
-        version="0.0.1",
+        version=version,
         author="Chris Laws",
         author_email="clawsicus@gmail.com",
         description="A Prometheus Python client library for asyncio-based applications",
         long_description="",
-        license="MIT License",
+        license="MIT",
         keywords=["prometheus", "monitoring", "metrics"],
         url="https://github.com/claws/aioprometheus",
         packages=["aioprometheus"],
         install_requires=requires,
         pyrobuf_modules="proto",
-        test_suite="tests",
         classifiers=[
             "Development Status :: 4 - Beta",
             "Intended Audience :: Developers",
-            "License :: OSI Approved :: Apache Software License",
+            "License :: OSI Approved :: MIT License",
             "Natural Language :: English",
             "Operating System :: OS Independent",
             "Programming Language :: Python :: 3.5",