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.

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.

• Take a while to lurk on the lists. Evergreen has both general and development mailing lists available with public archives. If your aim is to get a new feature added to Evergreen then learning how the lists operate culturally and who is a frequent poster will be very helpful. Watch the lists for a month or two and become familiar with what is appropriate for each, and what is not.
• Review the archives. We make the list archives public for two main reasons: accountability and project memory. If you have a question, check the archives first. If you don't find an answer there or you need further clarification, please ask on the appropriate list. The same rule applies for feature discussions. If a feature addition has been tabled then it is probably best to leave it tabled as a new community member, unless there is strong new evidence that it should be discussed again.
• Check the To-do and Software Bounties lists on the project wiki. Someone may already be working on the feature you'd like to implement.
• Familiarize yourself with the code. The Evergreen Subversion repository contains about 1.1 million lines of source code, documentation and data based on a simple find . -name "*[.pm|.pl|*.py|*.c|*.h|*.sql|*.js|*.xml|*.css|*.html|*.xhtml|*.ac|*.am|*.tt2|*.xul]" -exec cat {} \; | wc -l in the summer of 2010. That's a lot of fairly interdependent code, and contributors must learn what to touch and what not to touch.
• Install it. One of the best ways to become familiar with the code and the architecture is to go through the entire installation procedure laid out in the Project wiki. Having done this, you also now have a reference platform to start working on new contributions.

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.

We're not ashamed to admit that there might be bugs; no software is perfect. With so many possible combinations of software components and versions, we need to know about the bugs that you have found to improve Evergreen. A well-documented bug report can be a significant positive contribution to the project by helping the development team fix the problem quickly and efficiently. Although we understand that you might be very frustrated, please try to be polite when reporting a problem; remember that your bug report will generally be publicly visible, and it's a matter of human nature that you will likely get more attention to your problem if you are pleasant to work with.

The Evergreen project primarily uses the Evergreen and OpenSRF Launchpad instances to track reported bugs. To avoid duplication in the bug reporting database, search for an existing bug that matches your problem before opening a new bug. If you have found a new bug, try to be as specific as possible when reporting the problem; include information such as the specific versions of OpenSRF, Evergreen, PostgreSQL, XULRunner, and other components as well as the Linux distribution that you're using. Communication about the bug will occur on the bug form itself, and you will automatically be added to the email list for that bug to be notified when updates to the bug occur.

When problems are reported on the Evergreen and OpenSRF Launchpad instances, or requests for help are posted to the mailing lists, a positive response is a sign of a great community. Please try to remember that to reach the point of reporting a bug or asking for help, the person posting the bug is probably quite frustrated and some of that frustration might be evident in their language; focus on the technical problems underlying the bug report or help request and don't take any comments about the project personally. Keep in mind that your responses will be visible on the mailing list archives and in the bug database for perpetuity and represent one of the public faces of the Evergreen project: be nice!

If you wish to join the "Bug Wranglers" group that maintains the Evergreen bug reporting database, just add yourself to the team.

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 its slide into disrepair. The Documentation Interest Group (DIG) has tackled the task of writing and maintaining the Evergreen documentation, so if you are interested in contributing to the documentation efforts, please join the DIG!

• If you've spotted a section of documentation you'd like to work on (or even create entirely), ask about doing this on the Evergreen documentation mailing list. Someone else may have already claimed this section, so collaboration would be in order.
• Propose a simple addition or change. It is important that the project documentation have roughly the same voice throughout. The easiest way to accomplish this is to give existing documentation contributors a sample of what you want to add.
• Follow existing conventions. Based on the feedback from your sample, and informed by existing, surrounding documentation (assuming some exists), adopt a voice that makes sense in the section you are augmenting.
• Start writing! The documentation contributor list will be updated to include your name.

• Familiarize yourself with the code. If the documentation is regarding installation, make sure you have installed the components. If it's about configuration, make sure you have read and understand the code that uses the relevant configuration information.

• Use the UI. Yes, it sounds silly … but don't make any assumptions about what each interface does. Use it on the demo or development server and take screen shots where appropriate.
• Where appropriate, read the UI code. Not only could it improve your documentation by helping explain what is going on, you may even spot problems, bugs or inefficiencies!

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.

• Spot some trouble, report a bug in the Evergreen bug database, and possibly propose a solution. Bug fixes and minor adjustments to code are very important to the stability and longevity of the Evergreen project, and are treated as full contributions. As such, you will need to write up a basic functional description of the suspected issue for the community to discuss as a whole. If the change is truly trivial, a core member may simply fix the issue immediately. In this case you will be listed as a bug reporter in the next release of Evergreen.
• Wait for possible feedback. You can generally expect to hear back about a minor contribution proposal within a day or two. You may just get a simple "nod" from another developer on the list, in which case it's fine to proceed to the next step. Pay attention to all replies, and proceed as soon as you get the go-ahead.
• Build and submit a patch. Put together a patch that implements the fix and post it to the open-ils-dev mailing list. You will be informed of its status by email as soon as a core team member has the chance to look at it. For patch building guidelines, please see Submitting a Patch.
• Accept and incorporate feedback. If you receive any feedback from your patch posting, please incorporate it and reply to the feedback thread, or ask for clarification if you are unsure of anything. This may seem circuitous, but the next time any other community member submits a patch they may have learned from the public feedback you received and the updated patch you sent. In any case, this is expected to be rare for minor patches.
• It's in! After your code has been committed you will be informed by email and you will appear as a contributor in the release notes for the next version of Evergreen.

• Propose a design. Because Evergreen has not only a legacy of its own but a basic road map for future implementation, any new potential features need to be weighed against the overall strategic plan and internal architecture. You will need to write up a full functional and basic implementation proposal for the community to discuss as a whole. More information about what is expected in such a proposal for discussion can be found in the section entitled How to Propose Features.
• Wait for and expect feedback. It is highly unlikely that you are the only one interested in a particular feature, and time must be given for others to comment on the basic design. How much time depends on the breadth and depth of the change or addition proposed, but no less than a few days (more, if it's over a weekend, holiday or the relevant core team members are unavailable) will suffice. Expect both positive and negative technical feedback, as there will likely be competing and parallel ideas for any non-trivial change. Discussion should surround the proposal and suggestions for improvement will be made at this time. This is where the big-picture things are hashed out.
• Lather, Rinse, Repeat. It is expected that, following technical feedback from the community, and particularly from existing developers, you will incorporate relevant consensus building feedback into your design. Once there is positive consensus (as opposed to "acceptance by inaction"), proceed to the next step.
• Build a patch. Having come to a general consensus with the community, create some working code against your test installation. For patch building guidelines, please see the section Submitting a Patch. Ideally, do your work in a publicly visible repository, such as the Evergreen Contributions Subversion repository, a Bazaar branch, or a git repo on Gitorious or similar public repository. Working in a public repository makes it possible for others to collaborate with you.
• Submit a patch for review. As a community project, the community will decide what code goes into the software. This effort will be lead by the core development team, those with Subversion commit privileges, and will be informed by anyone in the community that would like to comment. Patches will be reviewed based on the style of the new code in relation to surrounding, preexisting code (where applicable), equality with the proposal that met consensus, and overall quality.
• Accept and incorporate feedback. Contributed code, having been reviewed, may require some adjustment, and some discussion will happen here unless the patch is almost entirely without defect. In such cases, minor adjustments may be made by the committing core team member without further discussion.
• In the case of brand new algorithmic or feature additions, include the Developer Certificate of Origin (DCO) 1.1 in your final patch submission email. In order to make sure that no IP-protected code ever leaks into the Evergreen repository, we will need to have a DCO for all major contributions. This is not an assignment of copyright, nor an accusation of theft. It simply states that the code you submitted is yours to contribute, is unencumbered to the best of your knowledge, and that you are free to submit it without any restrictions, such as academic or employment ties. You can find a copy of the DCO 1.1 here.
• It's in! After your code has been committed you will be informed by email and you will appear as a contributor in the release notes for the next version of Evergreen.

• Identify an ancillary project that you would like to integrate with, or create for the support of, Evergreen. Evergreen proper can't (and shouldn't) contain everything useful to the project or the users. If you see a need that can be fulfilled by an outside resource, but would affect the overall project (such as installation or migration projects, or external activities that point to the Evergreen project) then it serves everyone, the community and the contributor, well to get buy-in and input from the Evergreen community. You're likely to find a great deal of help and enthusiasm, as well.
• Submit a basic proposal. Create a proposal following the guidelines in listed in the section How to Propose Features to lay out a plan.
• Wait for possible feedback. You can generally expect to hear back about an external contribution proposal within a day or two. Discussion is important here, though probably won't be as extensive as a non-trivial feature proposal. Wait until consensus is reached by discussion participants, and strongly consider any suggestions and feedback they provide.
• Go forth! (But keep us up to date) Build or integrate your solution after considering all feedback. Remember to announce the project's completion (or parts thereof) on both the open-ils-dev and open-ils-general mailing lists, so that any other community members who would like to can help you continue to improve the external component.

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 Evergreen development mailing list, collect the information required for the community to discuss the addition completely and thoroughly. The minimum requirements for this information are:

• Basic overview of the feature or change
• An explanation of the existing code – it's structure and purpose – if applicable
• An explanation of why this code needs to change, if applicable
• A full explanation of the new or replacement feature including implementation plans
• Analysis of what this change will effect in the existing code base
• Analysis of what ways, if any, this addition or change can be leveraged for future planned development

An emerging method of proposing features is to:

1. collect the information on a page on the Evergreen wiki in the dev:proposal namespace
2. add a Blueprint entry with the basic overview and a link to the corresponding wiki page
3. send the basic overview and links to the Blueprint and wiki page to the Evergreen development mailing list with a subject line beginning with Feature Proposal

To submit the patch, you can do either or both of:

• Attaching the patch to a new or existing bug in the Evergreen bug database
• Sending the patch to the Evergreen developer 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:

• Ensure that your patch is generated against the most recent version of the code, which for developers is trunk in the Evergreen Subversion repository.
• Try to make your patch as readable as possible by following the surrounding code-layout conventions. This makes it easier for the reviewer, and there's no point in trying to layout things differently. Also avoid unnecessary whitespace changes because they just distract the reviewer, and formatting changes will likely be removed by the committing core team member.
• The patch should be generated as a single file from the root of the repository. This is most easily achieved using the Subversion diff command after updating your working copy of the repository or module.

$ svn update
$ svn diff > filename.patch

• Evergreen is licensed under the GNU General Public License version 2 with the "either version 2 of the License, or (at your option) any later version" clause, so to be included, any submissions must either:
  • (preferably) be licensed under the GNU General Public License version 2 with the "either version 2 of the License, or (at your option) any later version" clause or
  • or be licensed under a license compatible with the GPL
• Please remember to include the Developer's Certificate of Origin (DCO) 1.1 in your final submission. The DCO is your statement that you either created the code, or have the right to contribute the code to the project.
• Provide an implementation overview, preferably in code comments. Following the surrounding code commenting style or the most common block comment style for the language are usually a good approaches.
• New feature patches should be accompanied by enough description to enable the documentation team to write something coherent about the new functionality.
• If you are adding a new feature, confirm that it has been tested thoroughly. Try to test the feature in all conceivable scenarios.
• If it is a performance patch, please provide confirming test results to show the benefit of your patch. It is OK to post patches without this information, though the patch will not be applied until somebody has tested the patch and found a significant performance improvement.

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 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
    it.

(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.