From 007f4ee2abf818b4b18b6e8347da1d4eb2e0ad9c Mon Sep 17 00:00:00 2001
From: Vasudev Kamath <kamathvasudev@gmail.com>
Date: Thu, 1 May 2014 22:04:11 +0530
Subject: [PATCH] Documentation updates

* doc/source/index.rst: pbr requires git tags to be signed for using it
  to generate version information. Added a note mentioning this
* doc/source/packagers.rst: documented SKIP_GENERATE_AUTHORS and
  SKIP_WRITE_GIT_CHANGELOG environment variable for packagers.

Change-Id: I153c26f0d6876729dfb95eed2ab031c2aaa890d5
Signed-off-by: Vasudev Kamath <kamathvasudev@gmail.com>
---
 doc/source/index.rst     |  5 +++++
 doc/source/packagers.rst | 22 ++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8c514fc9..590bb94b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -32,6 +32,11 @@ will be very similar to git describe. If you do, then we'll assume that's the
 version you are working towards, and will generate alpha version strings
 based on commits since last tag and the current git sha.
 
+.. note::
+
+   Note that `pbr` expects git tags to be signed, for using it to
+   calculate version.
+
 The versions are expected to be compliant with :doc:`semver`.
 
 AUTHORS and ChangeLog
diff --git a/doc/source/packagers.rst b/doc/source/packagers.rst
index b1ee3584..c7994329 100644
--- a/doc/source/packagers.rst
+++ b/doc/source/packagers.rst
@@ -57,3 +57,25 @@ source tarball to be skipped. Beware though, that because `pbr` packages
 automatically find all of the files, most of them do not have a complete
 `MANIFEST.in` file, so its possible that a tarball produced in that way will
 be missing files.
+
+AUTHORS and ChangeLog
+=====================
+
+`pbr` generates AUTHORS and ChangeLog files from git information. This
+can cause problem in distro packaging if packager is using git
+repository for packaging source. If that is the case setting
+`SKIP_GENERATE_AUTHORS`
+
+::
+
+   SKIP_GENERATE_AUTHORS=1
+
+will cause logic around generating AUTHORS using git information to be
+skipped. Similarly setting `SKIP_WRITE_GIT_CHANGELOG`
+
+::
+
+   SKIP_WRITE_GIT_CHANGELOG=1
+
+will cause logic around generating ChangeLog file using git
+information to be skipped.