doc/use-cases.txt

   1 Terminology
   2  There are four types of users: Maintainers, Developers, Bug-fixers,
   3  and regular Users. The first three are all Contributors.
   4
   5 Name: Maintainer (Contributor)
   6 Description: The Maintainer reviews commits and branches from other
   7 Contributors and decided which ones to integrate into a 'master' branch.
   8
   9 Name: Developer (Contributor)
  10 Description: The Developer contributes enhancements to the project,
  11 e.g. they add new content or improve existing content.
  12
  13 Name: Bug-fixer (Contributor)
  14 Description: The Bug-fixer locates 'bugs' (as something unwanted that
  15 needs to be corrected) in the content and 'fixes' them.
  16
  17 Name: User
  18 Description: The User uses the content, be it in their daily work or
  19 every now and then for a specific purpose.
  20
  21
  22 Use cases
  23
  24 A model where other Contributors review commits is assumed in all use
  25 cases. When referenced are made to a Contributor addressing another
  26 Contributor to adjust their behavior as the result of data mined, it
  27 should be kept in mind that the Contributor should foremost be the one
  28 to do this. Using this information to, say, spend more time checking
  29 ones own commits for bugs when working on a specific part of the
  30 content on ones own accord is is often more effective then doing
  31 so only after being asked. </disclaimer>? :P
  32
  33 Name: Finding a Contributor that is active in a specific bit of content.
  34 Description:
  35       Whenever a Contributor needs to know about other Contributors
  36 that are active in a specific part of the content they query git for
  37 this information. This could be used to figure out whom to send a copy
  38 of a commit (someone who has recently worked on the content a commit
  39 modifies is likely to be interested in such a commit). This
  40 information may be easily gathered with, say, git blame. Aggregating
  41 it's output (in the background if need be to maintain speedy response
  42 times), it is trivial to determine whether a Contributor has more
  43 commits/lines of change than a predefined amount. The main difference
  44 with git blame is that it's output is aggregated over the history of
  45 the content, for a specific Contributor, whereas git blame only shows
  46 the latest changes.
  47
  48 Name: Finding which commits touches the parts of the content that a
  49       commit touches.
  50 Description:
  51       There are several reasons that one might want to know which
  52 commit touches the parts of the content that a commit touches. This
  53 may be implemented similar to how git blame works only instead of
  54 'stopping' after having found the author of a line, the search
  55 continues up to a certain date in the past.
  56
  57 Name: Integrating the found 'bug introducing' commit with the git
  58       commit message system.
  59 Description:
  60       When a Bug-fixer sends out a commit to fix a bug it might be
  61 useful for them to find out where exactly the bug was introduced.
  62 Using the 'which commit touched the content this commit touches'
  63 technique optional candidates may be retrieved. After picking which of
  64 the found commits caused the bug, this information may then
  65 automatically added to the commit's description. This does not only
  66 allow the Bug-fixer to make clear the origin of their commit, but also
  67 make it possible to later unambiguously determine a bug/fix pair. Note
  68 that this is automated, no user input is required to determine which
  69 commit caused the bug, only the picking of 'cause' commits requires
  70 input from the user.
  71
  72 Name: Finding the Author that introduce a lot of/almost no bugs to
  73       the content.
  74 Description:
  75       Contributors might be interested to know which of the Developers
  76 introduce a lot of bugs, or the contrary, which introduce almost no
  77 bugs to the content. This information is highly relevant to the
  78 Maintainer as they may now focus the time they spend on reviewing
  79 commits on those that stem from Developers that turn out to often
  80 introduce bugs. On the other hand, Developers that usually do not
  81 introduce bugs need less reviewing time. While such information is
  82 usually known to the experienced Maintainer (as they know their main
  83 contributors well), it can be helpful to new maintainers, or as a
  84 pointer that the opinion of the Maintainer about a specific Developer
  85 needs to be adjusted. Bug-fixers on the other hand can use this
  86 information to address the Developer that introduces most of the bugs
  87 they fix, perhaps with advice on how to prevent future bugs from being
  88 introduced.
  89
  90 Name: Finding the Contributor that accepted a lot of/almost no bugs
  91       into the content.
  92 Description:
  93       Similar to the finding Authors that write the bugs, there are
  94 other Contributors that 'accept' the commit. Either passively, by not
  95 commenting when the commit is sent out for review, or actively, by
  96 'acknowledging' (acked-by), 'signing off' (signed-off-by) or 'testing'
  97 (tested-by) a commit. When actively doing so, this can later be traced
  98 and then be used in the same ways as for Authors.
  99
 100 Name: Finding parts of the content in which a lot of bugs are
 101       introduced and fixed
 102 Description:
 103       When a Developer decides to change part of the content, it would
 104 be interesting for them to know that many before them introduced bugs
 105 when working on that part of the content. Knowing this the Developer
 106 might ask for all such buggy commits to try and learn from the
 107 mistakes made by others and prevent making the same mistake. A
 108 Maintainer might use this information to spend extra time reviewing a
 109 commit from a 'bug prone' part of the content.
 110
 111 Name: Finding parts of the content a particular Contributor introduces
 112       a lot of/almost no bugs to.
 113 Description:
 114       When trying to decide whether to ask a specific Contributor to
 115 work on part of the content it might be useful to not only know how
 116 active they work on that part of the content, but also if they
 117 introduced a lot of bugs to that part, or perhaps fixed many. Similar
 118 to the more general case, this can be split out between modifying
 119 content and 'accepting' modifications. This information may be used to
 120 decide to ask a Contributor to spend more time on a specific part of
 121 the content before sending in a commit for review.
 122
 123 Name: Finding how many bugs were introduced/fixed in a period of time
 124 Description:
 125       As bugs are recognized by their fixes, it is always possible to
 126 match a bug to it's fix. Both commits have a time stamp and with those
 127 the time between bug and fix can be calculated. Aggregating this data
 128 over all known bug(fixes) the amount of unfixed bugs may be found over
 129 a specified period of time. For example, finding the amount of fixed
 130 bugs between two releases, or how many bugs were not fixed within one
 131 release cycle. This number might then be calculated over several time
 132 frames (say, each release), after which it is possible to track
 133 'content quality' throughout releases. If this information is then
 134 graphed one can find extremes in this figure (for example, a release
 135 cycle in which a lot of bugs were fixed, or one that introduced many).
 136 Knowing this the Contributors may then determine the cause of such and
 137 learn from that.
 138
 139 Name: Finding how much work a contributor has done over a period of
 140       time.
 141 Description:
 142       When working in a team in which everybody is expected to do
 143 approximately the same amount of work it is interesting to see how
 144 much work each Contributor actually does. This allows the team to
 145 discuss any extremes and attempt to handle these as to distribute the
 146 work more evenly.
 147       When work is being done by a large group of people it is
 148 interesting to know the most active Contributors since these usually
 149 are the ones with most knowledge on the content. The other way around,
 150 it is possible to determine if a specific Contributor is 'active
 151 enough' for a specific task (such as mentoring).
 152
 153 Name: Finding whether a Contributor is mostly a Developer or a
 154       Bug-fixer.
 155 Description:
 156       To all Contributors it is interesting to know if they spend most
 157 of their time fixing bugs, or contributing enhancements to the content.
 158 This information could also be queried over a specific time frame, for
 159 example 'weekends vs. workdays' or 'holidays vs. non-holidays'.
 160