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