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