From e5b7dae85e38bf646009b16c48c387150d7da6e3 Mon Sep 17 00:00:00 2001
From: Markus Zoeller <mzoeller@de.ibm.com>
Date: Fri, 23 Mar 2018 09:26:16 +0100
Subject: [PATCH] Add usage with travis CI to docs

This change adds a description how to use reno within a travis CI
setup. It's neither a bug in Travis nor in reno. It's just a
different set of expectations of these two. As reno gets used
outside of OpenStack too, it makes sense to clarify the usage.

Change-Id: I675402402d5eb3d9afd374c149b21c75977946c7
Related-bug: 1703603
---
 doc/source/user/usage.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst
index 944a03a..e660265 100644
--- a/doc/source/user/usage.rst
+++ b/doc/source/user/usage.rst
@@ -277,3 +277,29 @@ the CI jobs and other project-specific settings used for reno. Refer
 to the `Managing Release Notes
 <https://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes>`__
 section of the Project Team Guide for details.
+
+Within Travis CI
+================
+
+The `Travis CI <https://travis-ci.org/>`_ uses shallow git clones,
+which prevents reno from accessing the repo data it needs. You'll
+see an error message like the one mentioned in
+`Launchpad bug 1703603 <https://bugs.launchpad.net/reno/+bug/1703603>`_.
+
+To use reno within a Travis CI job, the cloned repository needs to be
+unshallowed in the ``.travis.yml`` control file with the command
+``git fetch --unshallow --tags``, like in this example:
+
+.. code-block:: yaml
+
+   ---
+   language: python
+
+   python:
+     - 2.7
+
+   install:
+     - git fetch --unshallow --tags
+
+   script:
+     - reno report .