= Creating Tickets
Alex Miller
2018-12-05
:type: dev
:toc: macro
:icons: font

ifdef::env-github,env-browser[:outfilesuffix: .adoc]

If you do not have a JIRA account, please follow the <<xref/../../community/contributing#_reporting_problems_and_requesting_enhancements,preferred process>> for filing an issue at https://ask.clojure.org[ask.clojure.org]. If you're interested in supplying patches or contributing to Clojure, please see the <<dev#,development overview>>.

== Creating Tickets

To create a ticket, you must already have a Clojure JIRA account. Issues for Clojure itself can be created in the https://clojure.atlassian.net/projects/CLJ[CLJ] project. Contrib projects will have a link to their JIRA project in the README.

== Qualities of a Great Ticket

All tickets should have:

* Type: Correct categorization as Defect, Enhancement (extension of existing feature), or Feature (new)
* Summary: concise summary of the problem
* Description: 
** Exactly one problem (if multiple, split across tickets and link)
** (If Defect) Reproducible demonstration of problem (commands that can be duplicated in a repl are preferred, particularly a plain Clojure repl, not a Leiningen repl), and a description of what you think should happen instead
** (If Enhancement) Statement of how this is encountered and why it is a problem worth solving.
** Links to relevant prior discussion if relevant
* Priority: categorize based on impact and whether this is a theoretical issue or one actually encountered in real code. This may be adjusted by the core team during triage.
* Labels: (see section below)

Tickets ready for screening should also have:

* Description:
** The cause of the problem
** List of alternatives to solving the problem
** Which approach is being pursued
** Name of current patch to consider
** A description of the changes in the patch - anything you can do to illuminate what the changes are and why you made them will help ticket screeners as they re-walk your steps.
** Benchmark data (if performance related)
* Patch attachment:
** Implementation that follows the approach specified in the description
** Tests as appropriate
 
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 as a summary of the essential problem, solution approach, and patch. It should not be necessary to read the the full ticket history to evaluate the patch. 

Patches may, over time, no longer apply to master. Screeners often update patches so they stay relevant (retaining attribution to the author), but you can do this work as well if you like.

== 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
* checkargs - additional argument checking for functions
* 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 - this is already covered by the issue type
* enhancement - this is already covered by the issue type
* patch - already covered by the patch field
* test - already covered by the patch field
