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
  37 @subheading Status
  38
  39 Open issues:
  40
  41 @itemize
  42
  43 @item
  44 New: the item was added by a non-member, despite numerous warnings
  45 not to do this.  Should be reviewed by the Bug Meister.
  46
  47 @item
  48 Accepted: the Bug Meister added it, or reviewed the item.
  49
  50 @item
  51 Started: a contributor is working on a fix.  Owner should change
  52 to be this contributor.
  53
  54 @end itemize
  55
  56
  57 Closed issues:
  58
  59 @itemize
  60
  61 @item
  62 Invalid: issue should not have been added in the current state.
  63
  64 @item
  65 Duplicate: issue already exists in the tracker.
  66
  67 @item
  68 Fixed: a contributor claims to have fixed the bug.  The Bug
  69 Meister should check the fix with the next official binary release
  70 (not by compiling the source from git).  Owner should be set to
  71 that contributor.
  72
  73 @item
  74 Verified: Bug Meister has confirmed that the issue is closed.
  75
  76 @end itemize
  77
  78
  79 @subheading Owner
  80
  81 Newly-added issues should have @emph{no owner}.  When a
  82 contributor indicates that he has Started or Fixed an item, he
  83 should become the owner.
  84
  85
  86
  87 @subheading Type
  88
  89 The issue's Type should be the first relevant item in this list.
  90
  91 @itemize
  92
  93 @item
  94 Type-Collision: overlapping notation.
  95
  96 @item
  97 Type-Defect: a problem in the core program.  (the @code{lilypond}
  98 binary, scm files, fonts, etc).
  99
 100 @item
 101 Type-Documentation: inaccurate, missing, confusing, or desired
 102 additional info.  Must be fixable by editing a texinfo, ly, or scm
 103 file.
 104
 105 @item
 106 Type-Build: problem or desired features in the build system.  This
 107 includes the makefiles, stepmake, python scripts, and GUB.
 108
 109 @item
 110 Type-Scripts: problem or desired feature in the non-build-system
 111 scripts.  Mostly used for convert-ly, lilypond-book, etc.
 112
 113 @item
 114 Type-Enhancement: a feature request for the core program.  The
 115 distinction between enhancement and defect isn't extremely clear;
 116 when in doubt, mark it as enhancement.
 117
 118 @item
 119 Type-Other: anything else.
 120
 121 @end itemize
 122
 123
 124 @subheading Priority
 125
 126 Currently, only Critical items will block a stable release.
 127
 128 @itemize
 129
 130 @item
 131 Priority-Critical: lilypond segfaults, or a regression occurred
 132 within the last two stable versions.  (i.e. when developing 2.13,
 133 any regression against 2.12 or 2.10 counts)
 134
 135 @item
 136 Priority-High: highly embarrassing items, and any regression
 137 against a version earlier than two stable versions.  (i.e. when
 138 developing 2.13, any regression against 2.8 or earlier)
 139
 140 @item
 141 Priority-Medium: normal priority.
 142
 143 @item
 144 Priority-Low: less important than normal.
 145
 146 @item
 147 Priority-Postponed: no fix planned.  Generally used for things
 148 like Ancient notation, which nobody wants to touch.
 149
 150 @end itemize
 151
 152
 153 @subheading Opsys
 154
 155 Issues that only affect specific operating systems.
 156
 157
 158 @subheading Other items
 159
 160 Other labels:
 161
 162 @itemize
 163
 164 @item
 165 Regression: it used to @strong{deliberately} work in an earlier
 166 stable release.  If the earlier output was accidental (i.e. we
 167 didn't try to stop a collision, but it just so happened that two
 168 grobs didn't collide), then breaking it does not count as a
 169 regression.
 170
 171 @item
 172 Patch: a patch to fix an issue is attached.
 173
 174 @item
 175 Frog: the fix is believed to be suitable for a new contributor
 176 (does not require a great deal of knowledge about LilyPond).  The
 177 issue should also have an estimated time in a comment.
 178
 179 @item
 180 Maintainability: hinders developent of LilyPond.  For example,
 181 improvements to the build system, or @qq{helper} python scripts.
 182
 183 @item
 184 Bounty: somebody is willing to pay for the fix.
 185
 186 @item
 187 Warning: graphical output is fine, but lilypond prints a
 188 false/misleading warning message.  Alternately, a warning should
 189 be printed (such as a bar line error), but was not.  Also applies
 190 to warnings when compiling the source code or generating
 191 documentation.
 192
 193 @item
 194 Security: might potentially be used.
 195
 196 @item
 197 Performance: might potentially be used.
 198
 199 @end itemize
 200
 201
 202 @node Adding issues to the tracker
 203 @section Adding issues to the tracker
 204
 205 This should only be done by the Bug Meister(s), or experienced
 206 developers.  Normal users should not do this; instead, they should
 207 follow the guidelines for @rweb{Bug reports}.
 208
 209
 210 @node Checking and verifying issues
 211 @section Checking and verifying issues
 212
 213 After each release (both stable and unstable):
 214
 215 @itemize
 216
 217 @item
 218 Regression test comparison: check the relevant version in
 219 @uref{http://lilypond.org/test/}.
 220
 221 @item
 222 Issues to verify:
 223 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
 224
 225 @end itemize
 226
 227 Once every year or so:
 228
 229 @itemize
 230
 231 @item
 232 Checking all regtests: although we have a system for checking the
 233 regtests between two versions, occasionally a bug will slip
 234 through the cracks.  It is therefore good to manually examine all
 235 the regtests (compare the images to the text description).
 236
 237 @item
 238 Checking all issues: we try to mark each Issue @q{fixed} when we
 239 fix it, but occasionally one or two issues will slip through the
 240 cracks.  It is therefore good to check all Issues. If you see the
 241 same (broken) output as the initial report, then simply post a
 242 "Problem still exists in 2.x.y" message to the issue.
 243
 244 @end itemize
 245
 246
 247 @node Summary of project status
 248 @section Summary of project status
 249
 250 The best overview of our current status is given by the grid view:
 251
 252 @example
 253 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
 254 @end example
 255
 256 Also of interest might be the issues hindering future development:
 257
 258 @example
 259 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
 260 @end example
 261
 262 Finally, issues tagged with @code{Frog} indicates a task suitable
 263 for a relatively new contributor.  The time given is a quick
 264 (inaccurate) estimate of the time required for somebody who is
 265 familiar with material in this manual, but does not know anything
 266 else about LilyPond development.
 267
 268 @example
 269 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
 270 @end example
 271
 272 @node Finding the cause of a regression
 273 @section Finding the cause of a regression
 274
 275 Git has special functionality to help tracking down the exact
 276 commit which causes a problem.  See the git manual page for
 277 @code{git bisect}.
 278
 279 This is a job that non-programmers can do; once a problematic
 280 commit is identified, the programmers' job is much easier.  In
 281 fact, for most regression bugs, the majority of the time is spent
 282 simply finding the problematic commit.
 283
 284