| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| contributing [2015/08/05 16:32] – remove errant newline gmcharlton | contributing [2023/06/01 12:02] (current) – update branch name from master to main gmcharlton |
|---|
| * [[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 |
| * 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. |
| |
