The Clojure contribution process is designed to allow for open collaboration while also insuring that each change to the code base is well planned and executed.

This diagram shows an outline of the process. The workflow is explained in greater detail below.

Creating Tickets

The first step in the contribution process is to open a ticket. Please do so through JIRA and not through GitHub. This ticket can be created by anyone with or without a CA. It is OK to create a ticket and submit a patch at the same time, but please be aware, if the ticket is later rejected, the time spend developing the patch will be lost. Therefore it is recommended that coding on non-trivial patches should be postponed until after the vetting process. One possible advantage to submitting a patch before the ticket is vetted, is that it might be vetted and screened all at once by the screener, if they choose to do that, saving some time.

Vetting

After a ticket has been created it must be vetted. The “vetters” are a group of people who have been assigned the task of providing high-level validation of tickets. For example, if someone submits a ticket that says “We should make all data structures mutable”, the vetters will most likely reject the ticket on the spot. However, a reproducible bug report affecting existing code will most likely be vetted without much ceremony. Several steps can be taken by ticket authors that will help insure that their request makes it through the vetting process in a timely fashion.

1) If the ticket represents a bug, please give example code of the problem. Vetters are asked to verify all bugs. A un-reproducible bug will be rejected outright.

2) If the ticket represents a feature request, please provide some extra information about the request that explains why the feature is needed, and why it cannot exist as a separate library in Clojure contrib. Often this extra information is a link to a mailing list discussion, an IRC log, or perhaps it evolved out of a conversation with Rich Hickey. In general, the more context given for a ticket, the more likely the it is to make it through the vetting process.

Development

After a ticket has been vetted, it moves into the development phase. At this point, patches will be created and attached to the ticket. This code can be written by anyone who has submitted a CA. Due to copyright restrictions any patches submitted by someone without a CA will not be accepted, and feature/fix will need to be recoded from scratch.

The core contributors to Clojure try to code patches for bugs first, and then move on to feature requests. Therefore if you have an accepted CA, there is a major feature that interests you, and it is missing a patch, feel free to code the patch yourself. As with most open source projects, if you find a missing feature bothersome, your are most likely the right person to code the implementation.

Screening

After the patch has been coded and attached to the ticket, the ticket will be “ready to screen”. The goal of screeners is to provide code-review and implementation oversight to new features and bugs. Where vetters review the high-level aspects of a ticket (is this feature needed?), screeners provide low-level oversight of the process (is this feature coded correctly?). If the screeners are uncomfortable with the patch, it will be marked as “incomplete” and sent back to the “vetted” phase to be refactored and screened again.

Approval

Once a patch has been screened, it is sent to Rich Hickey for final approval. Rich can perform one of three actions on the ticket. He can outright reject it (perhaps asking that it be put into a contrib library), he can approve it for the current release, or he can approve it for the next release.

If a ticket is marked for the current release, one of the Clojure committers will take the patches attached to the ticket and commit them to the github repository. At this point the ticket is marked as done, and the ticket number is placed into the changelog for the next release of Clojure.

One beta testing starts for a given version of Clojure all new features will be placed in the backlog for the next release, and only bug fixes will be accepted for the current release. Once the current version of Clojure has been released the next release backlog will be comited to the source repository.