Glossary

Approval status - the Approval field in a JIRA issue.
Clojure/core member - Contributor who has the approval to vet tickets in JIRA.
Contributor - Person who has signed the Clojure Contributor Agreement.
Defect - A bug in the code base.
Enhancement - A new feature in the code base.
Issue - A ticket in JIRA.
Screener - Contributor who is approved to screen tickets.
Task - Work that must be done outside the code base.

Submitting patches to Clojure and Clojure Contrib

If you've got a bug fix or feature you'd like to submit to the Clojure, Clojure Contrib or Clojure CLR projects, first - thanks! Before you get too deep into the code, please make sure you review the contributing guidelines -- it's important to submit a Contributor's agreement as detailed on that page. Once it's been received (your name will appear on the contributor's list on that page), you can join the clojure-dev Google group. Anyone with a CA can become a member of our Confluence and JIRA. Just sign up (please use a recognizable name), then ask on the clojure-dev group and I'll bump up your membership level to make edits.

So You Have an Idea...

In order to make sure you are not duplicating effort, fixing a feature, or planning an unwelcome change, please coordinate with the community, by first examining existing issues (clojure's , contrib's ), and discussing your patch plan on the clojure-dev Google group.

Track it in JIRA

If you've got the go-ahead and there isn't already a ticket for your issue/feature, please create one. Make sure the ticket includes a link to the discussion in the Google Group or IRC, so someone reviewing your ticket can quickly get up to speed. Assign yourself to the ticket so people know you are working on it. Please don't assign things to others without their consent.

Prioritization and Milestones (Committers)

Committers use the prioritization and milestone fields. If you are a the committer for a lib, please don't change the priority or the default milestone assignment.

Development

Once you're ready to craft your code, the first thing you'll need is a clone of the Clojure or Contrib repository. The examples below are for the contrib project -- for submissions to Clojure itself, remove "-contrib" from the examples:

Is the patch performance-sensitive? If so, is the approach appropriate?

After review, if you are happy, you should

Set the approval of the ticket to screened

If you own the lib in question, you can set approval to accepted, and deploy the change

If you are not happy

Add a comment to the ticket, explaining what the issues are

Set the approval of the ticket to 'Incomplete'

Set the waiting-on of the ticket to the person who created the patch

If you aren't sure

Get a second opinion, and note this in the comments

Set the waiting-on to Rich or Stu, if appropriate

Closing Tickets (Committers)

If you are a committer on a lib, you can screen tickets and close them all in one step. Alternately, you can review tickets screened by others, and then either close them or bounce them back (as in the Screening step above).

While you have the ability to just push your stuff into the repo, please use the tickets systems too. It makes a fine todo system, helps organize bigger milestones, lets others hop in and help or provide input, and provides a place to hang discussions about your changes.

Problems?

Clojure is Stricter than Contrib

The expectation of stability and performance is much higher for Clojure than for Clojure Contrib. Rich personally reviews every change to Clojure. To save Rich's time, other committers may do the work in git. When this happens, you can see Rich's review process in JIRA, both in the comments and in tickets being moved from 'Screened' to 'Ok' by Rich.

Speculative Changes

If you want to share work-in-progress on some feature you are not yet ready to propose with a ticket, you can post a patch made as above, or a pointer to your repo, to the clojure-dev group.

Thanks for contributing to Clojure!

Screening Process Described

An issue is created in JIRA that expresses some unit of work that is desired. This could be a defect, an enhancement or a task.

Clojure/core team vets the ticket, and changes the approval status to Vetted, indicating this is a problem that we want to solve.
Next a contributor writes a patch to address a defect or enhancement, and attaches the patch to the issue. The contributor should also indicate what kind of patch this is in the ticket. The approval status is then set to test, indicating it is dev complete.

A screener will review the issue and marks the approval status as Screened. This will set the issue to waiting on Rich.

Rich comes along and blesses the issue by setting it the approval status to OK, meaning the code is ready to build & push to git.

When the code has been pushed, the issue is marked as Resolved.

At any point along this path a Screener can mark the issue as Declined, meaning it is not something we are going to address.

Also, at any point a Clojure/core member can mark the approval status as Incomplete. This indicates more information is needed to continue work on the issue. There is also an optional Waiting On? field that should be set to indicate who is expected to provide the additional information