Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added labels stuff

...

Qualities of a Great Ticket

All tickets should have:

  • Concise title
  • Summary of exactly one problem or enhancement
    • Enhancements should have a statement of a problem they solve
  • Correct categorization (Bug/Enhancement)Type: Correct categorization (Defect or Enhancement)
  • Summary: concise title
  • Description: 
    • Exactly one issue (if multiple, split across tickets and link)
    • (If Defect) Reproducible demonstration of problem (commands that can be duplicated in a repl are preferred)
    • (If Enhancement) Statement of the what should be improved 
    • Links to relevant prior discussion on clojure-dev, IRC, or email thread as appropriate
  • Name of current patch under consideration

Bugs should have:

  • Reproducible demonstration of problem (repl output is preferred, but test or benchmark may also be okPriority: categorize based on impact and whether this is a theoretical issue or one actually encountered in real code
  • Labels: (see section below)

Tickets ready for screening should also have:

  • Description:
    • The cause of the problem
    • An accurate description of the approach being pursued to solve the problem
  • A patch implementing that approach
  • Tests demonstrating the patch
    • Name of current patch to consider
    • Summary or reference to alternative approaches that were considered
  • Patch attachment:
    • Implementation that follows the approach specified in the description
    • Tests as appropriate
    • Benchmark data (if performance related)
 
Example:
 
This is an example of how the description might look once a ticket has gone through screening - it starts with a succinct description of the problem and a demonstration that can be tried at the REPL. That may be all that exists when the ticket comes into the system. By the time it gets through screening, we should expect to see the dev's analysis of the cause of the problem, the solution that is being offered (and possibly alternatives that were considered), and the patch currently implementing the solution and test.
 
Adding odd numbers doesn't work. 

user> (+ 2 2)
4
user> (+ 1 3)
ClassCastException

Cause:  Never implemented odd number adding in the Compiler! See the missing branch in FooExpr.

Solution:  Fully implemented the branch for odd numbers to be just like even numbers. Considered just getting rid of addition altogether but I guess people use it.

Patch: add-odd-3.patch

Tend Your Ticket

As work progresses on a ticket, it is common for it to accumulate discussion between submitter, screeners, and patch developers. As this occurs, it is essential to edit the ticket description to stay up to date . This most commonly means listing the current patch under consideration and a concise as a summary of the essential problem, solution approach, and solutionpatch. It may also be useful to list considered alternative solutions and why they were rejected.should not be necessary to read the the full ticket history to evaluate the patch.

 

Labels

The following labels should be used to tag specific categories (sometimes these are useful for searching):

  • aot - ahead-of-time compilation bugs
  • compiler - Clojure compiler
  • deftype - types
  • defrecord - records
  • docstring - function docstrings
  • documentation - clojure.org docs or other doc-related issues
  • edn - EDN
  • errormsgs - improving (or sometimes adding) an error message returned by Clojure
  • interop - Java interop
  • io - clojure.java/io 
  • math - arithmetic issues - overflow, underflow, etc
  • memory - memory issues (GC, head holding, locals clearing, etc)
  • performance - make it faster!
  • print - print and pprint
  • protocols - defprotocol
  • reader - reader (either clojure or edn)
  • reducers
  • repl - usability on the repl (doc, source, apropos, etc)
  • string - clojure.string, subs, etc
  • typehints - their definition or application
  • walk - clojure.walk
  • zip - clojure.zip

DO NOT use these tags:

  • bug or enhancement - this is already covered by the issue type
  • patch and test - already covered by the patch field