Procedures and conventions for contributing to the Evergreen project

A major goal of the Evergreen ILS Project is to become a long term, sustainable, community driven development effort.  As such, it is necessary to define in concrete terms the acceptable procedures by which one can contribute to the overall improvement of Evergreen.  There are many ways in which one can contribute, including, but not limited to, QA, bug fixes, code clean up, new features, enhancements to existing features, entirely new subsystems, end user documentation, technical documentation and translation/internationalization.  All of these efforts are important for the ongoing success of the project, and none are any more important than the others for the long term success of Evergreen as a whole.  The overarching goal of these procedures is to facilitate as much communication as possible among community members, and that communication occur early and often during the development process.  It is the opinion of the original core development team that this communication is absolutely key to our continued success.

This is a living document.  It is meant to provide the reader, and potential contributor, with a set of clear guidelines that will help the contributor usher new material through the community process in an efficient manner .  It is not meant to create undue roadblocks to any individual or set of potential contributors.  If defects or inefficiencies in this process are identified and brought to the attention of the community to be addressed, then this set of guidelines may be amended from time to time.  Nothing is written in stone.

Throughout this document you will see references to the "core team" or "committers".  This is the group of Evergreen developers that have Subversion commit privileges, and are responsible for integrating code contributions directly into the source of Evergreen.  From time to time, and as individual community members become more familiar and skilled with the complete codebase of Evergreen, some individuals may be asked to join the core team.  We see this as both an honor and a responsibility, as this group is charged with being the final quality control mechanism for the source code, as well as helping other less experienced community members come up to speed.  It is not simply a way to get code into Subversion, but also about mentoring new contributors and helping to keep the overall vision of the project in focus, tempered by the history and evolution of the code and lessons learned from past successes and failures.


  1. Before you contribute
  2. Code Contributions
    1. Small Additions and Changes
    2. Large Additions and Changes
    3. External Contributions
  3. Documentation Contributions
  4. How to Propose Features
  5. Submitting a Patch

Before you contribute

Owing to the fact that Evergreen has a wide, diverse and evolving code and documentation base, there are some basic steps a potential contributor should take to familiarize himself with both the existing code as well as the development and support community surrounding the project.  These are not hard and fast requirements, but it is strongly suggested that any new contributor follow these steps in order to ease ones integration into the community.

Having spent some time learning the culture and code, and familiarizing yourself with the history of the project, it's time to consider contributing.  Each successive time you contribute you can expect the process to become smoother as the core team learns about your coding style and skills, and as you learn what is expected and acceptable to the project and the community.

Code Contribution

One of the most visible ways to contribute is through actual code.  All contributions and contributors will arrive at Evergreen from different backgrounds and will carry with them some legacy of their origin.  Once reaching Evergreen, though, some certainties can be guaranteed:

  1. Each contribution will be judged individually on its technical merits as long as the contributor has followed these guidelines
  2. All contributions that are to be considered must follow project guidelines and community customs

It is expected that the person proposing a change or addition will be the one developing the patch, or in the case of a very large addition or change, leading the implementation effort of all those interested in helping code the feature.  If you find an open proposal that you would like to work on with the original proposer then you should feel free to ask about collaborating.

Small additions and changes

Large additions and changes

External contributions

Documentation Contribution

Certainly one of the most important parts of any software package is documentation.  Good technical and end user documentation can mean the difference between a project's eventual broad acceptance or it's slide into disrepair.

General guidelines for documentation contributions

Additional guidelines for technical documentation contributions

Additional guidelines for end user documentation contributions

How to Propose Features

Proposing a new non-trivial addition to the Evergreen project is fairly easy.  After making sure that someone else hasn't claimed the feature by asking on the open-ils-dev list, just collect all the information required for the community to discuss the addition completely and thoroughly.  The minimum requirements for this information are:

This should be sent to the open-ils-dev mailing list with a subject line beginning with Feature Proposal.

Submitting a Patch

You will need to submit the patch to the open-ils-dev mailing list. It will be reviewed by other contributors to the project and will be either accepted or sent back for further work. To help ensure your patch is reviewed and committed in a timely fashion, please try to make sure your submission conforms to the following guidelines:

Even if you pass all of the above, the patch might still be rejected for other reasons. Please be prepared to listen to comments and make modifications.  You will be notified via email when the patch is applied, and you will appear as a contributor in the next version of the release notes.

Developer's Certificate of Origin

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Signed-off-by: [submitter's name and email address here]

© 2006-2007, Georgia Public Library Service.  Distributed under the Creative Commons Attribution-ShareAlike 2.5 license.