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.

Contents

Before you contribute
Code Contributions

Small Additions and Changes
Large Additions and Changes
External Contributions

Documentation Contributions
How to Propose Features
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.

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 CVS (now Subversion) repository contains about 240,000 lines of source code, documentation and data based on a simple 'cvs extract -r HEAD ILS' in the spring of 2007. 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.

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:

Each contribution will be judged individually on its technical merits as long as the contributor has followed these guidelines
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

Spot some trouble and 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 the section entitled 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.

Large additions and changes

Propose a design. Because Evergreen has not only a legacy of it's 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 entitled Submitting a Patch.
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 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 always 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.

External contributions

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.

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

Ask on the mailing list. If you've spotted a section of documentation you'd like to work on (or even create entirely), ask about doing this on the open-ils-general 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.

Additional guidelines for technical documentation contributions

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.

Additional guidelines for end user documentation contributions

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!

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:

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

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:

Ensure that your patch is generated against the most recent version of the code, which for developers is SVN trunk.
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 Subverision diff command after updating your working copy of the repository or module.
```
      $ svn update
      $ svn diff > filename.patch
    
```
Evergreen is licensed under the GNU GPL, so any submissions must conform to the GPL or a compatible license to be included. Please remember to include the DCO 1.1 in your final submission!
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 also be accompanied by documentation patches suitable for inclusion in the documentation wiki.
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


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]