- Developing and submitting patches
- Vetting tickets, and screening and committing patches
- Screening process description and figure
How a Ticket Becomes a Commit
This page describes the overall workflow for how tickets (bugs and enhancement requests) make their way through the JIRA ticketing system and ultimately become part of Clojure, ClojureScript, and ClojureCLR.
The overall process described here has several goals:
- Maintain Clojure quality
- Fix problems that are important to users
- Engage the community in working toward the best possible Clojure
There are several groups involved in this process with increasing levels of capability:
- Anyone - anyone can submit a bug or enhancement request to Clojure once you have created a Clojure JIRA account
- Contributors - anyone that has signed the contributor agreement can supply patches or work or otherwise work on improving tickets
- Screeners - a smaller group of trusted individuals have been granted the ability to move tickets through (some of) the stages of the process, in particular the Triage and Screening activities
- BDFL - Rich Hickey is the creator and Benevolent Dictator for Life of what goes into Clojure. Stuart Halloway also has a special level of access and typically commits patches to Clojure.
There are several important fields on a ticket that jointly determine it's "state" in the workflow below. Some key fields to know about:
- JIRA status- these govern the default JIRA workflow and consist of Open, In progress, Reopened, Resolved, Closed
- The Clojure workflow does not really distinguish between these much other than general open/closed differentiation
- Approval- a custom field that is (mostly) how Screeners change the state of a ticket
- None - new ticket
- Triaged - screener has approved the ticket as worth working on
- Vetted - screener and Rich have approved the ticket as worth working on
- Screened - screener has approved a ticket's patch for review by Rich
- Incomplete - screener has requested improvements to a ticket or patch
- Ok - Rich has approved the ticket for inclusion
- Not Approved - ?? deprecated?
- Test - ?? deprecated?
- Patch- qualifies the kind of patch attached
- None - no patch
- Code - code only, no test
- Code and Test - code and test
- Fixed, New, Invalid, Accepted - ?? deprecated?
- Fix version
- Release X.X - specific targeted release
- Backlog - will consider in future release
- Approved Backlog, Reviewed Backlog - ?? deprecated?
- Resolution- when a ticket is closed, it will have a resolution
- Declined - did not accept a ticket for work
The diagram below documents the process used for how tickets make their way through the system. The rounded boxes represent states in the workflow. They have well defined criteria (which sometimes cover multiple fields) such that each of these states can have a report. In general, a single line state indicates the Approval state. If additional fields are in play, they are listed after the state.
The colored blocks represent activities performed by different groups - the colors correspond to the group (Orange = contributors, Blue = screeners, Green = BDFL). Diamonds represent decisions to be made during an activity. Activities are described in more detail below the diagram
- Who: Screeners
- Report: Open tickets
- Goal: decide whether the bug or enhancement described in the ticket is actually a real bug or enhancement.
- For bugs, there should be some demonstration that the problem actually exists (output from a repl, test, etc).
- Comment on ticket to ask for more information, better description, better demonstration of problem, etc
- Close with Resolution=Decline, reasons:
- Not a bug: submitter misunderstood or misused a feature
- Scope too big: feature may be better served by creating a page in the design wiki than in a ticket
- Enhancement not wanted: enhancement is not something we want to do
- Duplicate: of existing ticket
- Set Approval=Triaged - problem is ok
- If needed, adjust ticket to standards of triaged ticket below
- Who: Rich
- Report: Triaged tickets
- Goal: second check on whether the bug/enhancement is worth working on and decision of whether it's suitable for the next release.
- Close w Resolution=Declined - as above, ticket may not be something we want to address
- Set Approval=Vetted - problem is good
- Who: Rich
- Report: Vetted tickets
- Goal: determine whether a ticket is in scope for next release or should be in backlog
- Set Fix Version to "Backlog" - don't want to fix it in the next release
- Set Fix Version to current release
- If does not have patch, will show up in "Needs Patch" report
- If does have patch, will show up in "Screenable" report
- Dev Patch
- Who: contributors (anyone with signed CA)
- Report: "Needs Patch" and "Incomplete" tickets
- Goal: create a high quality ticket and patch for consideration (see sections below)
- Edit ticket or update patch to address problems or gaps based on comments.
- Who: Screeners
- Reports: Screenable tickets (for new vetted tickets with patches), Incomplete tickets that have changed recently and may need re-review
- Goal: verify that ticket and patch are ready for Rich to review.
- The quality bar is HIGH - the ticket and patch should be perfect
- Set Approval=Incomplete and add comment describing needed improvements
- Set Approval=Screened - ticket and patch are perfect and Rich should review
- Final screening
- Who: Rich
- Report: Screened tickets
- Goal: Rich blessing the change
- Set Approval=Incomplete - ticket or patch needs improvement
- Set Approval=OK - everything is good, ready to commit
- Who: Stu H (usually)
- Report: OK tickets
- Goal: Final review of change and commit to Clojure source
- Set Approval=Accepted and commit patch to clojure src
- Backlog Review
- Who: Rich (primarily)
- Report: Backlog tickets
- Goal: See if backlogged tickets should be pulled into next release
- Set Fix Version from Backlog to current release
- (or don't to leave in Backlog)
See Submitting bugs and enhancement requests if you are looking for instructions on submitting a bug report or enhancement request. If you are a Clojure contributor having problems with Clojure changes, submitting patches, the status of a patch, or other questions related to changes to Clojure or the contrib libraries, please ask a question on the clojure-dev Google group.
Thanks for contributing to Clojure!