Skip to end of metadata
Go to start of metadata


  • Improve quality and quantity of community contribution
    • Communicate ticket and patch expectations
    • Communicate where help is needed
    • Give visibility into what's happening in the process
    • Create dashboard showing ticket metrics/reports
  • Improve efficiency of existing workflow
    • Clarify existing workflow and update documents to describe it correctly
    • Create blessed reports (and dashboard) that everyone can use to see tickets in each state
    • Improve clarity of docs describing each activity, what report to use, actions to take, etc
    • Switch to JIRA workflow (see Clojure workflow (experimental) for Chas's prior work on this)
    • Maximize value of core Friday time by preparing places where we need help

This diagram represents an updated view of the process:

Notes about the various activities:

  • Triage
    • 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). 
    • Actions:
      • 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
  • Vetting
    • 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.
    • Actions:
      • Close w Resolution=Declined - as above, ticket may not be something we want to address
      • Set Approval=Vetted - problem is good
  • Release scheduling
    • Who: Rich
    • Report: Vetted tickets
    • Goal: determine whether a ticket is in scope for next release or should be in backlog
    • Actions:
      • 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)
    • Actions: 
      • Edit ticket or update patch to address problems or gaps based on comments. 
  • Screening 
    • 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
    • Actions:
      • 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
    • Actions:
      • Set Approval=Incomplete - ticket or patch needs improvement 
      • Set Approval=OK - everything is good, ready to commit
  • Commit 
    • Who: Stu H (usually)
    • Report: OK tickets 
    • Goal: Final review of change and commit to Clojure source
    • Actions:
      • 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
    • Actions:
      • Set Fix Version from Backlog to current release 
      • (or don't to leave in Backlog)

Qualities of a triaged ticket

  • Ticket describes exactly one problem
  • Problem stated clearly
  • Demonstrate the problem as concisely as possible - via repl, test, etc

Qualities of a ticket ready for screening

  • (all properties of triaged ticket)
  • Proposed solution summarized (the end result of all comment or external discussion)
  • Name of patch for consideration - patch approach should match proposed solution
  • Alternate solutions considered and why rejected
  • Links to more commentary if external to the ticket

Qualities of a good patch

  • No extraneous changes (whitespace, unrelated mods, etc)
  • Docstrings should be adjusted if necessary
  • Test should be included if at all possible


ReportProjectStatusApprovalPatchFix versionResolution
VettedCLJO/IP/ROVetted NULL 
Needs PatchCLJO/IP/ROVettedNULL<nextRelease> 
IncompleteCLJO/IP/ROIncomplete <nextRelease> 
ScreenableCLJO/IP/ROVettedNOT NULL<nextRelease> 
OkCLJO/IP/ROOk <nextRelease> 


BacklogCLJR/C  Backlog, Approved Backlog 
DeclinedCLJR/C   Declined



  • O/IP/RO = Open / In Progress / Reopened
  • R/C = Resolved / Closed
Additional JIRA changes that may be useful:
  • Shared filter noise: 
    • We could lock down the Global Permission for Sharing Objects so that only a small group can share filters (this would reduce shared filter noise at the expense of someone not being able to share something useful)
    • A select group (currently Jira administrators) can change ownership of filters which allows them to take ownership and modify existing filters - this might be useful in maintaining a standard set
    • Could create filter naming conventions but no way to enforce that 
  • CLJ project "versions"
    • There are functions (latestReleasedVersion and earliestUnreleasedVersion) that would be very useful in making the reports above constant across releases but the latest/earliest is based on lexical sorting and right now things like "Approved Backlog" sort prior to all other "Release x.y". We could change naming schemes to make this better. It is typical for people to use just numbers "1.4" instead of "Release 1.4" in other JIRA projects for example. This has a side effect of sorting all versions ahead of pseudo stuff.
  • Deprecated fields
    • Approval - "Not Approved" and "Test" are not used in current process and could go away
    • Fix version - currently have "Approved Backlog", "Backlog", "Reviewed Backlog" which can all just be "Backlog" per Rich
    • Patch - many possible values right now but largely Code and Code&Test are the two that are used. Simplify?
  • Workflow
    • We could actually define and use a JIRA workflow to manage this process rather than our own conventions
    • Chas has built experimental versions of this. Might need to change process a bit.
    • This would make the workflow more concrete and would reduce many simple errors by requiring fields to be set at certain transitions, etc.