Documentation/contributor/issues.itexi

   1 @c -*- coding: utf-8; 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 The difference between Priority-Medium and Priority-Low is not
 153 well-defined, both in this policy and in practice.  The only
 154 answer we can give at the moment is @qq{look at existing items in
 155 of the same type, and try to guess whether the priority is closer
 156 to the Medium items or Low items}.  We're aware of the ambiguity,
 157 and won't complain if somebody picks a @q{wrong} value for
 158 Medium/Low.
 159
 160
 161 @subheading Opsys
 162
 163 Issues that only affect specific operating systems.
 164
 165
 166 @subheading Other items
 167
 168 Other labels:
 169
 170 @itemize
 171
 172 @item
 173 Regression: it used to @strong{deliberately} work in an earlier
 174 stable release.  If the earlier output was accidental (i.e. we
 175 didn't try to stop a collision, but it just so happened that two
 176 grobs didn't collide), then breaking it does not count as a
 177 regression.
 178
 179 @item
 180 Patch: a patch to fix an issue is attached.
 181
 182 @item
 183 Frog: the fix is believed to be suitable for a new contributor
 184 (does not require a great deal of knowledge about LilyPond).  The
 185 issue should also have an estimated time in a comment.
 186
 187 @item
 188 Maintainability: hinders developent of LilyPond.  For example,
 189 improvements to the build system, or @qq{helper} python scripts.
 190
 191 @item
 192 Bounty: somebody is willing to pay for the fix.
 193
 194 @item
 195 Warning: graphical output is fine, but lilypond prints a
 196 false/misleading warning message.  Alternately, a warning should
 197 be printed (such as a bar line error), but was not.  Also applies
 198 to warnings when compiling the source code or generating
 199 documentation.
 200
 201 @item
 202 Security: might potentially be used.
 203
 204 @item
 205 Performance: might potentially be used.
 206
 207 @end itemize
 208
 209
 210 @node Adding issues to the tracker
 211 @section Adding issues to the tracker
 212
 213 This should only be done by the Bug Meister(s), or experienced
 214 developers.  Normal users should not do this; instead, they should
 215 follow the guidelines for @rweb{Bug reports}.
 216
 217
 218 @node Checking and verifying issues
 219 @section Checking and verifying issues
 220
 221 After each release (both stable and unstable):
 222
 223 @itemize
 224
 225 @item
 226 Regression test comparison: check the relevant version in
 227 @uref{http://lilypond.org/test/}.
 228
 229 @item
 230 Issues to verify:
 231 @uref{http://code.google.com/p/lilypond/issues/list?can=7}.
 232
 233 @end itemize
 234
 235 Once every year or so:
 236
 237 @itemize
 238
 239 @item
 240 Checking all regtests: although we have a system for checking the
 241 regtests between two versions, occasionally a bug will slip
 242 through the cracks.  It is therefore good to manually examine all
 243 the regtests (compare the images to the text description).
 244
 245 @item
 246 Checking all issues: we try to mark each Issue @q{fixed} when we
 247 fix it, but occasionally one or two issues will slip through the
 248 cracks.  It is therefore good to check all Issues. If you see the
 249 same (broken) output as the initial report, then simply post a
 250 "Problem still exists in 2.x.y" message to the issue.
 251
 252 @end itemize
 253
 254
 255 @node Summary of project status
 256 @section Summary of project status
 257
 258 The best overview of our current status is given by the grid view:
 259
 260 @example
 261 @uref{http://code.google.com/p/lilypond/issues/list?mode=grid&y=Priority&x=Type&cells=ids}
 262 @end example
 263
 264 Also of interest might be the issues hindering future development:
 265
 266 @example
 267 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Maintainability&mode=grid&y=Priority&x=Type&cells=ids}
 268 @end example
 269
 270 Finally, issues tagged with @code{Frog} indicates a task suitable
 271 for a relatively new contributor.  The time given is a quick
 272 (inaccurate) estimate of the time required for somebody who is
 273 familiar with material in this manual, but does not know anything
 274 else about LilyPond development.
 275
 276 @example
 277 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:Frog&mode=grid&y=Priority&x=Type&cells=ids}
 278 @end example
 279
 280 @node Finding the cause of a regression
 281 @section Finding the cause of a regression
 282
 283 Git has special functionality to help tracking down the exact
 284 commit which causes a problem.  See the git manual page for
 285 @code{git bisect}.  This is a job that non-programmers can do,
 286 although it requires familiarity with git, ability to compile
 287 LilyPond, and generally a fair amount of technical knowledge.
 288
 289 Even if you are not familiar with git or are not able to compile
 290 LilyPond you can still help to narrow down the cause of a regression
 291 simply by downloading the binary releases of different LilyPond
 292 versions and testing them for the regression.  Knowing which version
 293 of LilyPond first exhibited the regression is helpful to a developer
 294 as it shortens the @code{git bisect} procedure described above.
 295
 296 Once a problematic commit is identified, the programmers' job is
 297 much easier.  In fact, for most regression bugs, the majority of
 298 the time is spent simply finding the problematic commit.
 299