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