Procedures and conventions for contributing to the Evergreen project
For the Evergreen ILS Project to continue as a sustainable, community-driven development effort, the community needs 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 cleanup, 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 with the goal of providing 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 git commit privileges and are responsible for integrating code contributions directly into the source of Evergreen. To see a list of these core committers, go to the contributors page. 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 the git repository, 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.
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 oneself with both the existing code as well as the development and support community surrounding the project. These are not hard and fast requirements, but the community strongly encourages any new contributor to 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.
Reporting bugs
We're not ashamed to admit that there might be bugs. In fact we are positive there are; 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.
If you wish to join the "Bug Wranglers" group that maintains the Evergreen bug reporting database, just add yourself to the team. For details on how we use Launchpad (such as what the different bug statuses mean), read the Evergreen Bug Wrangler FAQ.
Offering support
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!
Translating Evergreen
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 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 DIG!
General guidelines for documentation contributions
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.
This wiki is a repository of information contributed by the Evergreen community that, while useful, isn't suitable for inclusion in the official technical documentation. As such, it's an excellent place to contribute informal documentation, helpful resources, and other content that the Evergreen community may find useful. To learn more about contributing to the wiki, visit the
Draft Wiki Guidelines.
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!
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
The community expects 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,
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. Be sure to subscribe to the bug so that you can be alerted to any feedback you might receive.
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, in which case it's fine to proceed to the next step. Pay attention to all replies.
Build and submit a patch. Put together a patch that implements the fix, post a link to the patch on the Launchpad bug, and add a pullrequest tag to the bug. Testers and core team members will update you on the status of the patch by posting comments to the LP bug. For patch building guidelines, please see
Submitting Code to the Project.
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 from a posted comment on the Launchpad bug. You will also 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 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. Expectations for a development proposal 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 feedback into your design. Once there is positive consensus (as opposed to "acceptance by inaction"), proceed to the next step.
Write the code. Having come to a general consensus with the community, create some working code against your test installation. Ideally, do your work in a publicly visible repository, such as one created for you on the
Evergreen community Git server repository (preferred), a
Bazaar branch, or a git repository on
Gitorious or similar public repository. Working in a public repository makes it possible for others to collaborate with you.
Submit your code to the project by posting a link to your branch in a Launchpad bug. As a community project, the community decides what code goes into the official releases of the software on the
Evergreen downloads page. This effort is led by the core development team and can be informed by anyone in the community who wants to comment. Code contributions are reviewed based on the style of the new code in relation to surrounding, pre-existing code (where applicable), equality with the proposal that met consensus, and overall quality. The process for submitting code is covered in the following section,
Submitting code to the project.
Accept and incorporate feedback. Contributed code, having been reviewed, may require some adjustment, and further discussion will often happen as more developers try out your code. In such cases, minor adjustments may be made by the committing core team member without further discussion.
It's in! After your code has been committed you will be informed from a posted comment on the Launchpad bug. You will also 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.
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 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:
-
add a
Launchpad bug with the basic overview and a link to the corresponding wiki page
-
Submitting code to the project
To submit code to the project, you can either create a branch in a publicly visible git repository or generate a git-formatted patch, then call attention to your contribution by either or both of:
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 ensure your submission conforms to the following guidelines:
Ensure that your branch or patch is developed against the most recent version of the code, which for developers is the main branch in the
Evergreen Git repository.
Try to make your changes 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 lay out things differently. Also, avoid unnecessary white space changes because they just distract the reviewer, and formatting changes will likely be removed by the committing core team member.
If you are submitting a patch rather than pointing at a branch in a public repository, use the Git format-patch command after updating your working copy of the repository or module as follows:
$ git checkout -b working_branch main
# hack away
$ git commit -as # for example
# if you're just working on a couple patches in a minor topic
# branch which you're not publishing as such
$ git fetch
$ git rebase origin
# for example for a topic branch that you've published and that
# others are pulling from, you don't want to rebase. Instead you can do
$ git pull
# then to create the patch(es)
$ git format-patch origin
Use descriptive commit messages:
Starting with a short (less than 80 characters) one-line summary. This summary is important because it is all that shows up in many interfaces, and there is limited space.
Add a blank line to separate the summary from the body of the commit message.
Add several sentences that describe the state of the code and behavior before the commit, and the state of the code and behavior after the commit. For example:
Serial holdings display consistency fix
When holdings are sourced from both MFHD and the DB, display may be
inconsistent due to a hard-coded ', ' in Serial.pm. This patch works around
the problem by storing generated_coverage as a JSON array instead of a string,
leaving display formatting to the OPAC.
For more information on how the Evergreen project uses Git, visit the
git page on this wiki.
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:
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.
For all significant code contributions, please use git's
sign-off feature to assert that the code you are submitting is in accordance with the Developer Certificate of Origin (
DCO) 1.1. To ensure that the Evergreen project has the right to redistribute all of the code in the repository, we ask for a DCO for all major contributions. This is not an assignment of copyright; the DCO 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 beyond the license under which you have submitted the code. Some employers or academic institution claim ownership over code that is written in certain circumstances, so please do due diligence to ensure that you have the right to submit the code. You can find a copy of the
DCO 1.1 here.
All patches should follow these QA guidelines for patch submission:
Any time a patch adds or alters a stored procedure, pgTAP tests that exercise its intended functionality should be included.
A change to database or Perl code that fixes a bug should be accompanied by a Perl (t or live_t) or pgTAP regression test – or by a statement from the patch author explaining why a test is infeasible without significant refactoring. In the latter case, it is expected that an extra signoff be obtained before the patch is merged.
New features should be accompanied by a file in the repository under the docs/RELEASE_NOTES_NEXT/ directory. The file should be in asciidoc format and contain enough description to enable the documentation team to write something coherent about the new functionality. The name of the file should match the feature. No numbering, etc. is required. With each release, the contents of this directory will be appended to the release notes.
See Tips for Writing Release Notes Bug fix patches should explain how to test the bug fix in the commit message.
Test your code; our project is deployed in many different environments and we don't want a bug fix or new feature for your environment to break when deployed in a different environment. If possible, include unit tests in your contribution to demonstrate that the code does what is supposed to, and to help prevent others from breaking your code in the future.
If it is a performance enhancement, please provide confirming test results to show the benefit of your changes. You can post changes without this information, though changes will not be applied until somebody has tested the code 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]
© 2006-2007, Georgia Public Library Service. Distributed under the Creative Commons Attribution-ShareAlike 2.5 license.