Evergreen DokuWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[contributing:contributors|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 [[contributing:contributors|code]] and [[evergreen-docs:digparticipants|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.

  * Take a while to lurk on [[http://evergreen-ils.org/communicate/mailing-lists/|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.
  * [[http://georgialibraries.markmail.org/search/|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 to see if your idea has been submitted to [[https://bugs.launchpad.net/evergreen|Launchpad]].  Someone may already be working on the feature you'd like to implement.
  * Familiarize yourself with the code.  The [[http://git.evergreen-ils.org/?p=Evergreen.git;a=summary|Evergreen Git repository]] contains a lot of source code, documentation and data. There is a lot of interdependent code, and contributors must learn how the different pieces interact. Read the [[eg_developer_overview|Evergreen Developer Overview]] for a high level view of the code.
  * 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.

===== 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 [[https://bugs.launchpad.net/evergreen|Evergreen]] and [[https://bugs.launchpad.net/opensrf|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 [[https://launchpad.net/~evergreen-bugs|the team]].  For details on how we use Launchpad (such as what the different bug statuses mean), read the [[dev:bug_wrangler:faq|Evergreen Bug Wrangler FAQ]].

===== Offering support =====

When problems are reported on the [[https://bugs.launchpad.net/evergreen|Evergreen]] and [[https://bugs.launchpad.net/opensrf|OpenSRF]] Launchpad instances, or requests for help are posted to the [[http://evergreen-ils.org/listserv.php|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 =====

To learn how you can help translate Evergreen into your language, see [[eg_translations|Evergreen translations]].

===== 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 [[evergreen-docs:dig|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 [[evergreen-docs:dig|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 [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation|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 [[webteam:draft_guidelines|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, [[contributing#reporting bugs|report a bug]] in the [[https://bugs.launchpad.net/evergreen|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 [[contributing#submitting_code_to_the_project|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 [[http://evergreen-ils.org/dokuwiki/doku.php?id=contributing#how_to_propose_features|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 [[http://git.evergreen-ils.org/|Evergreen community Git server]] repository (preferred), a [[https://code.launchpad.net/evergreen|Bazaar branch]], or a git repository on [[http://gitorious.org|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  [[http://evergreen-ils.org/downloads|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 [[contributing#How to Propose Features|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 [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-dev|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:

  - collect the information on a page on the Evergreen wiki in the [[http://evergreen-ils.org/dokuwiki/doku.php?idx=dev%3Aproposal|dev:proposal namespace]]
  - add a [[https://bugs.launchpad.net/evergreen|Launchpad bug]] with the basic overview and a link to the corresponding wiki page
  - send the basic overview and links to the Launchpad bug and wiki page to the [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-dev|Evergreen development mailing list]] and/or the [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general|general mailing list]] with a subject line beginning with Feature Proposal


==== 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:

  * Create a new or modify an existing bug in the [[https://bugs.launchpad.net/evergreen|Evergreen bug database]]. If you have created a publicly visible branch, point to it in the body of the bug  and add the tag **pullrequest** so that we can easily find your contribution on our [[https://bugs.launchpad.net/evergreen/+bugs?field.tag=pullrequest|list of outstanding pull requests]].

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 [[http://git.evergreen-ils.org/?p=Evergreen.git;a=summary|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:
<code bash>
$ 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
</code>
  * 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:<code>
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.
</code>
  * For more information on how the Evergreen project uses Git, visit the [[dev:git]] page on this wiki.
  * Evergreen is licensed under the [[http://www.gnu.org/licenses/gpl-2.0.html|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 [[http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses|compatible with the GPL]]
  * 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 [[http://git.evergreen-ils.org/?p=Evergreen.git;a=blob;f=DCO-1.1.txt;hb=HEAD|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.
    * Changes to the Angular staff client should be run through a linter to catch inconsistencies and common errors (cd Open-ILS/src/eg2 && npx ng lint).
  * 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. [[contributing: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 ====

<file>
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]
</file>


© 2006-2007, Georgia Public Library Service.  Distributed under the [[http://creativecommons.org/licenses/by-sa/2.5/|Creative Commons Attribution-ShareAlike 2.5 license]].