gitstats: Expanded the documentation of the bug module
authorSverre Rabbelier <sverre@rabbelier.nl>
Wed, 30 Jul 2008 21:50:52 +0000 (30 23:50 +0200)
committerSverre Rabbelier <sverre@rabbelier.nl>
Wed, 30 Jul 2008 21:50:52 +0000 (30 23:50 +0200)
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

index 6ab7d19..17032d9 100644 (file)
@@ -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