From 1055ae4f1b1e17a50f97103c5a171ff1862f3711 Mon Sep 17 00:00:00 2001
From: Sverre Rabbelier <sverre@rabbelier.nl>
Date: Wed, 30 Jul 2008 23:50:52 +0200
Subject: [PATCH] gitstats: Expanded the documentation of the bug module

After having to explain on the mailing list exactly what
the command does, it made sense to put that explanation in
the documentation.
---
 doc/gitstats-bug.txt | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/doc/gitstats-bug.txt b/doc/gitstats-bug.txt
index 6ab7d19..17032d9 100644
--- a/doc/gitstats-bug.txt
+++ b/doc/gitstats-bug.txt
@@ -4,6 +4,77 @@ The purpose of the bug module is to gather statistics on
 bugfixes within the content, and to aggregate this
 information to provide with a report of the last N commits.
 
+The metrics used in this module are:
+* Does a commit belong to a specific branch. This can be
+used, for example, to mark commits on a maintenance as
+bugfixes with 99% reliability. Whenever multiple refs point
+to the same commit though, the first ref passed by
+'git for-each-ref' will be listed if that commit is the one
+the searched commit belongs to. As such, you need to make
+sure your regexp catches those refs.
+
+* Does a commit fully revert another one. That is, if you
+make a commit, and then revert it, the revert will be
+detected as having reverted the earlier commit.
+
+* Does the commit message match a certain regexp. For
+example, if it contains the word "fixes", mark it as a fix.
+
+* Does the commit diff match a specified regexp. A change
+from "test_expect_failure" -> "test_expect_success" could
+indicate that the commit is a bugfix.
+
+- (not tweaked yet) Does a commit partially revert another
+one. This needs some tweaking, otherwise small changes are
+quickly seen as similar. (If you have two unrelated
+one-liners, and you set it to ignore one difference...)
+
+You have to configure a few things to get useful results.
+Configuration is trivially done with:
+'git config GitStats.key value'. It is also possible to
+override most options on the commandline when running the
+metric.
+
+The following optiosn are available:
+* 'GitStats.branch_filter', this defines the regexp that,
+when matched, indicates that a branch is a maintenance
+branch. When not set, the branch check will be skipped.
+
+* 'GitStats.branch_filter_rating', the amount by which the
+'bugfix rating' should be increased when the above filter
+matches on a certain commit.
+
+* 'GitStats.debug', whether to enable debug information.
+
+* 'GitStats.diff_filter', this defines the regexp that,
+when matched, indicates that a commit is a bugfix.
+
+* 'GitStats.diff_filter_rating', the amount by which the
+'bugfix rating' should be increased when the above filter
+matches on a certain commit.
+
+* 'GitStats.msg_filter', this defines the regexp that,
+when matched, indicates that a commit is a bugfix.
+
+* 'GitStats.msg_filter_rating', the amount by which the
+'bugfix rating' should be increased when the above filter
+matches on a certain commit.
+
+* 'GitStats.ignore_parents', when set, the ancestry of each
+commit will be retrieved during the 'belongs to' metric,
+which cuts down execution time by a lot on large repo's,
+but causes a slow down on small repo's. When unset, it
+defaults to disabled for repo's with less than 1000
+commits, and is enabled for those larger than 1000.
+
+* 'GitStats.limit', the amount of commits that should be
+examined by default by 'stats.py bug -a', this defaults
+to 10, but can be set to a higher value for small repo's.
+
+* 'GitStats.revert_rating', the amount by which the
+'bugfix rating' should be increased when the above filter
+matches on a certain commit.
+
 Currently the available metrics in the bug module are the
 following:
 * Determine whether a specific commit is a bugfix based on
-- 
2.11.4.GIT