Add versioning helpers

conftest.py

@@ -68,6 +68,7 @@ def pytest_configure(config):
             SENTRY_ALLOW_ORIGIN='*',
             CELERY_ALWAYS_EAGER=True,
             TEMPLATE_DEBUG=True,
+            PROJECT_ROOT=where_am_i,
             TEMPLATE_DIRS=[os.path.join(where_am_i, 'tests', 'contrib', 'django', 'templates')],
             ALLOWED_HOSTS=['*'],
         )

docs/config/index.rst

@@ -13,7 +13,7 @@ As of Raven 1.2.0, you can now configure all clients through a standard DSN
 string. This can be specified as a default using the ``SENTRY_DSN`` environment
 variable, as well as passed to all clients by using the ``dsn`` argument.
 
-::
+.. code-block:: python
 
     from raven import Client
 
@@ -24,6 +24,26 @@ variable, as well as passed to all clients by using the ``dsn`` argument.
     client = Client('http://public:secret@example.com/1')
 
 
+A reasonably configured client should generally include a few additional settings:
+
+.. code-block:: python
+
+    import raven
+
+    client = raven.Client(
+        dsn='http://public:secret@example.com/1'
+
+        # inform the client which parts of code are yours
+        # include_paths=['my.app']
+        include_paths=[__name__.rsplit('.', 1)[0]],
+
+        # pass along the version of your application
+        # release='1.0.0'
+        # release=raven.fetch_package_version('my-app')
+        release=raven.fetch_git_sha(os.path.dirname(__file__)),
+    )
+
+
 The Sentry DSN
 --------------
 
@@ -115,6 +135,17 @@ This will override the ``server_name`` value for this installation. Defaults to
 
     name = 'sentry_rocks_' + socket.gethostname()
 
+
+release
+~~~~~~~~
+
+The version of your application. This will map up into a Release in Sentry.
+
+::
+
+    release = '1.0.3'
+
+
 exclude_paths
 ~~~~~~~~~~~~~
 

raven/__init__.py

@@ -11,6 +11,7 @@ import os
 import os.path
 from raven.base import *  # NOQA
 from raven.conf import *  # NOQA
+from raven.versioning import *  # NOQA
 
 
 __all__ = ('VERSION', 'Client', 'load', 'get_version')

raven/exceptions.py

@@ -16,3 +16,7 @@ class RateLimited(APIError):
     def __init__(self, message, retry_after=0):
         self.retry_after = retry_after
         super(RateLimited, self).__init__(message, 429)
+
+
+class InvalidGitRepository(Exception):
+    pass

raven/versioning.py

@@ -0,0 +1,33 @@
+from __future__ import absolute_import
+
+__all__ = ('fetch_git_sha', 'fetch_package_version')
+
+import os.path
+import pkg_resources
+
+from .exceptions import InvalidGitRepository
+
+
+def fetch_git_sha(path, head='master'):
+    """
+    >>> fetch_git_sha(os.path.dirname(__file__))
+    """
+    revision_file = os.path.join(path, '.git', 'refs', 'heads', 'master')
+    if not os.path.exists(revision_file):
+        if not os.path.exists(os.path.join(path, '.git')):
+            raise InvalidGitRepository('%s does not seem to be the root of a git repository' % (path,))
+        raise InvalidGitRepository('Unable to find ref to head "%s" in repository' % (head,))
+
+    fh = open(revision_file, 'r')
+    try:
+        return fh.read().strip()
+    finally:
+        fh.close()
+
+
+def fetch_package_version(dist_name):
+    """
+    >>> fetch_package_version('sentry')
+    """
+    dist = pkg_resources.get_distribution(dist_name)
+    return dist.version

tests/versioning/tests.py

@@ -0,0 +1,18 @@
+from __future__ import absolute_import
+
+from django.conf import settings
+
+from raven.versioning import fetch_git_sha, fetch_package_version
+
+
+def test_fetch_git_sha():
+    result = fetch_git_sha(settings.PROJECT_ROOT)
+    assert result is not None
+    assert len(result) == 40
+    assert isinstance(result, basestring)
+
+
+def test_fetch_package_version():
+    result = fetch_package_version('raven')
+    assert result is not None
+    assert isinstance(result, basestring)