| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| contributing [2015/07/15 15:32] – Adding new QA guidelines and updating some bits to better match up with current processes. Moving most of the discussion to LP instead of mailing list/Blueprints. klussier | contributing [2023/06/01 12:02] (current) – update branch name from master to main gmcharlton |
|---|
| ====== 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 long-term, 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. | 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. | 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. |
| * [[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 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. | * 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. | * 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. |
| |
| 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]]. | 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 ===== |
| |
| 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! |
| | |
| | ===== Translating Evergreen ===== |
| | |
| | To learn how you can help translate Evergreen into your language, see [[eg_translations|Evergreen translations]]. |
| |
| ===== Documentation Contribution ===== | ===== Documentation Contribution ===== |
| - 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://bugs.launchpad.net/evergreen|Launchpad bug]] 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 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 | - 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 |
| |
| |
| 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: | 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 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 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. | * 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: | * 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> | <code bash> |
| $ git checkout -b working_branch master | $ git checkout -b working_branch main |
| |
| # hack away | # hack away |
| * All patches should follow these QA guidelines for patch submission: | * 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. | * 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 | * 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. |
| accompanied by a Perl (t or live_t) or pgTAP regression test – or by a | |
| statement from the patch author explaining that a test is infeasible | |
| without significant refactoring. | |
| * 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]] | * 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. | * 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 environment 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. | * 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. | * 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. |
| |
