Documentation/contributor/issues.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2 @node Issues
   3 @chapter Issues
   4
   5 This chapter deals with defects, feature requests, and
   6 miscellaneous development tasks.
   7
   8 @menu
   9 * Introduction to issues::
  10 * Issue classification::
  11 * Adding issues to the tracker::
  12 * Checking and verifying issues::
  13 * Summary of project status::
  14 * Finding the cause of a regression::
  15 @end menu
  16
  17
  18 @node Introduction to issues
  19 @section Introduction to issues
  20
  21 First, @qq{issue} isn't just a politically-correct term for
  22 @qq{bug}.  We use the same tracker for feature requests and code
  23 TODOs, so the term @qq{bug} wouldn't be accurate.
  24
  25 Second, the classification of what counts as a bug vs. feature
  26 request, and the priorities assigned to bugs, are a matter of
  27 concern @strong{for developers only}.  If you are curious about
  28 the classification, read on, but don't complain that your
  29 particular issue is higher priority or counts as a bug rather than
  30 a feature request.
  31
  32
  33 @node Issue classification
  34 @section Issue classification
  35
  36 Status values:
  37
  38 @itemize
  39
  40 @item
  41 New: the item was added by a non-member.  Should be reviewed by
  42 the Bug Meister.
  43
  44 @item
  45 Accepted: the Bug Meister added it, or reviewed the item.
  46
  47 @item
  48 Started: a programmer is working on a bugfix.  (used infrequently,
  49 but should be used more often)
  50
  51 @end itemize
  52
  53 Closed status values:
  54
  55 @itemize
  56
  57 @item
  58 Invalid: issue should not have been added in the current state.
  59
  60 @item
  61 Duplicate: issue already exists in the tracker.
  62
  63 @item
  64 Fixed: programmer claims to have fixed the bug.  The Bug Meister
  65 should check the input code in an official binary release.
  66
  67 @item
  68 Verified: Bug Meister has confirmed that the issue is closed.
  69
  70 @end itemize
  71
  72 Type labels:
  73
  74 @itemize
  75
  76 @item
  77 Type-Defect: a problem that requires no (or very little) new code
  78 to fix.
  79
  80 @item
  81 Type-Enhancement: a problem (or new feature) that requries a
  82 significant amount of new code.
  83
  84 @item
  85 Type-Collision: overlapping notation.  (this label takes
  86 precedence over -Defect and -Enhancement)
  87
  88 @item
  89 Type-Task: not used, I think.  TODO: start using it or delete it.
  90
  91 @item
  92 Type-Other: anything else.  TODO: start using it or delete it.
  93
  94 @end itemize
  95
  96 Priority labels:
  97
  98 @itemize
  99
 100 @item
 101 Priority-High: lilypond segfaults.
 102
 103 @item
 104 Priority-Regression: it used to work.
 105
 106 @item
 107 Priority-Medium: normal priority; this is the highest priority a
 108 non-crashing, non-regression bug report can receive.
 109 (regardless of the perceived importance)
 110
 111 @item
 112 Priority-Low: less important than normal.
 113
 114 @item
 115 Priority-Postponed: no fix planned.  Generally used for things
 116 like Ancient notation, which nobody wants to touch.
 117
 118 @end itemize
 119
 120 Opsys lables: pretty self-explanatory.
 121
 122 Other lables:
 123
 124 @itemize
 125
 126 @item
 127 Patch: a patch to fix an issue is attached.
 128
 129 @item
 130 Frog: the fix is believed to be suitable for a new contributor
 131 (does not require a great deal of knowledge about LilyPond).  The
 132 issue should also have an estimated time in a comment.
 133
 134 @item
 135 Security: not used.  TODO: delete, unless anybody is serious about
 136 this.
 137
 138 @item
 139 Performance: not used.  TODO: delete.
 140
 141 @item
 142 Usability: not used.  TODO: delete.
 143
 144 @item
 145 Maintainability: hinders developent of LilyPond.  For example,
 146 improvements to the build system, or @qq{helper} python scripts.
 147
 148 @item
 149 Bounty: somebody is willing to pay for the fix.
 150
 151 @item
 152 Engraving-nitpick: output is not beautiful, but not strictly
 153 speaking @qq{wrong}.  For example, a slur shape which does not
 154 collide with any notation, but looks ugly.
 155
 156 @item
 157 Warning-nitpick: graphical output is fine, but lilypond prints a
 158 false/misleading warning message.
 159
 160 @end itemize
 161
 162
 163 @node Adding issues to the tracker
 164 @section Adding issues to the tracker
 165
 166 FIXME: prettify.
 167
 168 only done by Bug Meister, unless you're really certain you know
 169 what you're doing.
 170
 171
 172
 173 @node Checking and verifying issues
 174 @section Checking and verifying issues
 175
 176 After each release (both stable and unstable):
 177
 178 @itemize
 179
 180 @item
 181 Regression test comparison: check the relevant version in
 182 @uref{http://lilypond.org/test/}.
 183
 184 @item
 185 Issues to verify:
 186 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
 187
 188 @end itemize
 189
 190 Once every year or so:
 191
 192 @itemize
 193
 194 @item
 195 Checking all regtests: although we have a system for checking the
 196 regtests between two versions, occasionally a bug will slip
 197 through the cracks.  It is therefore good to manually examine all
 198 the regtests twice a year or so (compare the images to the text
 199 description).
 200
 201 @item
 202 Checking all issues: we try to mark each Issue @q{fixed} when we
 203 fix it, but occasionally one or two issues will slip through the
 204 cracks.  It is therefore good to check all Issues. If you see the
 205 same (broken) output as the initial report, then simply post a
 206 "Problem still exists in 2.x.y" message to the issue.
 207
 208 @end itemize
 209
 210
 211 @node Summary of project status
 212 @section Summary of project status
 213
 214 The best overview of our current status is given by the grid view:
 215
 216 @example
 217 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
 218 @end example
 219
 220 Also of interest might be the issues hindering future development:
 221
 222 @example
 223 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
 224 @end example
 225
 226 Finally, issues tagged with @code{Frog} indicates a task suitable
 227 for a relatively new contributor.  The time given is a quick
 228 (inaccurate) estimate of the time required for somebody who is
 229 familiar with material in this manual, but does not know anything
 230 else about LilyPond development.
 231
 232 @example
 233 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
 234 @end example
 235
 236
 237 @node Finding the cause of a regression
 238 @section Finding the cause of a regression
 239
 240 Git has special functionality to help tracking down the exact
 241 commit which causes a problem.  See the git manual page for
 242 @code{git bisect}.
 243
 244 This is a job that non-programmers can do; once a problematic
 245 commit is identified, the programmers' job is much easier.  In
 246 fact, for most regression bugs, the majority of the time is spent
 247 simply finding the problematic commit.
 248
 249