User Tools

Site Tools


contributing

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
contributing [2011/05/14 13:55] – more gitification gmcharltoncontributing [2023/06/01 12:02] (current) – update branch name from master to main gmcharlton
Line 1: Line 1:
 ====== Procedures and conventions for contributing to the Evergreen project ====== ====== 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.
  
-A major goal of the Evergreen ILS Project is to become a long termsustainable, 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 projectand 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 readerand potential contributorwith 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 addressedthen this set of guidelines may be amended from time to time.  Nothing is written in stone.
  
-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 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 otherless 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.
- +
-Throughout this document you will see references to the "core team" or "committers" This is the group of Evergreen developers that have Subversion commit privilegesand 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 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.+
  
 ===== Before you contribute ===== ===== 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 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.+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/listserv.php|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.+  * 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 Evergreenthen 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.   * [[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 the [[dev:summer of coding ideas|potential projects]] list on the project wiki.  Someone may already be working on the feature you'd like to implement. +  * 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 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'a lot of fairly interdependent code, and contributors must learn what to touch and what not to touch.+  * 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.   * 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. 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.
Line 23: Line 21:
 ===== Reporting bugs ===== ===== Reporting bugs =====
  
-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.+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. 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 ===== ===== Offering support =====
Line 31: Line 31:
 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! 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!
  
-If you wish to join the "Bug Wranglers" group that maintains the Evergreen bug reporting databasejust add yourself to [[https://launchpad.net/~evergreen-bugs|the team]].+===== Translating Evergreen ===== 
 + 
 +To learn how you can help translate Evergreen into your languagesee [[eg_translations|Evergreen translations]]. 
 ===== Documentation Contribution ===== ===== 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 the [[evergreen-docs:dig|DIG]]!+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 ==== ==== General guidelines for documentation contributions ====
Line 42: Line 45:
   * 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.   * 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.   * 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 ==== ==== Additional guidelines for technical documentation contributions ====
Line 47: Line 52:
   * 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.   * 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 ====+==== 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.   * 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.
Line 59: Line 64:
   - All contributions that are to be considered must follow project guidelines and community customs   - 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 proposerthen you should feel free to ask about collaborating.
-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 ==== ==== 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 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+  * 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 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+  * 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 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 [[contributing#submitting_a_patch|Submitting a Patch]]. +  * Build and submit a patch.  Put together a patch that implements the fixpost a link to the patch on the Launchpad bug, and add 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. +  * 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 patchthey 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. +  * 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 ==== ==== 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 as a whole.  More information about what is expected in such a proposal for discussion can be found in the section entitled [[http://evergreen-ils.org/dokuwiki/doku.php?id=contributing#how_to_propose_features|How to Propose Features]]. +  * 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 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 feedbackas 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. +  * 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, RinseRepeat.  It is expected that, following technical feedback from the communityand 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. +  * Lather, rinserepeat.  It is expected that, following technical feedback from the community andparticularlyfrom 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. 
-  * 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 one created for you on the [[http://git.evergreen-ils.org/|Evergreen community Git server]] Subversion repository, a [[https://code.launchpad.net/evergreen|Bazaar branch]], or a git repo on [[http://gitorious.org|Gitorious]] or similar public repository. Working in a public repository makes it possible for others to collaborate with you. +  * 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 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. +  * Submit your code to the project by posting 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 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+  * 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. 
-  * 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 [[http://git.evergreen-ils.org/?p=Evergreen.git;a=blob;f=DCO-1.1.txt;hb=HEAD|DCO 1.1 here]]+  * 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.
-  * 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 ==== ==== External contributions ====
Line 106: Line 108:
  
   - 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]]   - 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://blueprints.launchpad.net/evergreen|Blueprint entry]] with the basic overview and a link to the corresponding wiki page +  - 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 Blueprint and wiki page to the [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-dev|Evergreen development mailing list]] with a subject line beginning with Feature Proposal+  - 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 a Patch ====+==== Submitting code to the project ====
  
-To submit the patch, you can do either or both of:+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:
  
-  * Attaching the patch to a new or existing bug in the [[https://bugs.launchpad.net/evergreen|Evergreen bug database]] +  * 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]].
-  * Sending the patch to the [[http://libmail.georgialibraries.org/mailman/listinfo/open-ils-dev|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:+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 patch is generated against the most recent version of the code, which for developers is the master branch in the [[http://git.evergreen-ils.org/?p=Evergreen.git;a=summary|Evergreen Git repository]]. +  * 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 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. +  * 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. Alsoavoid unnecessary white space 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 single file from the root of the repository. This is most easily achieved using the Git ''format-patch'' command after updating your working copy of the repository or module+  * If you are submitting a patch rather than pointing at 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> <code bash>
-$ git checkout -b working_branch master+$ git checkout -b working_branch main
  
 # hack away # hack away
Line 139: Line 140:
 # then to create the patch(es) # then to create the patch(es)
 $ git format-patch origin $ 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> </code>
   * For more information on how the Evergreen project uses Git, visit the [[dev:git]] page on this wiki.   * For more information on how the Evergreen project uses Git, visit the [[dev:git]] page on this wiki.
Line 144: Line 156:
     * (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     * (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]]     * or be licensed under a license [[http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses|compatible with the GPL]]
-  * Please remember to sign off your patches.  A sign-off by you, the author, signifies your 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.   * 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. +  * 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]]. 
-  * If you are adding a new feature, confirm that it has been tested thoroughlyTry to test the feature in all conceivable scenarios+  * All patches should follow these QA guidelines for patch submission: 
-  * If it is a performance patch, please provide confirming test results to show the benefit of your patchIt 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. +    * 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. [[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 bug fix or new feature for your environment to break when deployed in a different environmentIf 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 changesYou 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. 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 ====
  
contributing.1305395707.txt.gz · Last modified: 2022/02/10 13:33 (external edit)

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.