diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..7902775db --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,271 @@ +============== + Contributing +============== + +Bug reports, feature requests, and code contributions are encouraged +and welcome! + +Bug reports and feature requests +-------------------------------- + +If you find a bug or have a feature request, please search for +`already reported problems +`_ before +submitting a new issue. + +Code contributions +------------------ + +We follow typical `GitHub flow +`_. + +1. Fork this repository into your personal space. +2. Start a new topical branch for any contribution. Name it sensibly, + say ``improve-fix-search-user-preferences``. +3. Test your branch on a local site. If everything works as expected, + please `sign your commits + `_ + to indicate its quality. +4. Create `logically separate commits + `_ + for logically separate things. +5. Please add any ``(closes #123)`` or ``(addresses #123)`` directives + in your commit log message if your pull request closes or addresses + an open issue. +6. Issue a pull request. If the branch is not quite ready yet, please + indicate ``WIP`` (=work in progress) in the pull request title. + +Developer Guidelines +-------------------- + +Here is more detailed checklist of things to do when contributing code +to Invenio. + +1. **Before starting any wider-impact changes, submit a ticket and use a + discussion channel.** + + * Found a bug in a module and have a fix for it? Great, please + jump right in! + + * Have a new feature request or thinking of a new facility that + would impact several modules? Submit a ticket and discuss the + change before starting any implementation. + + * Small intra-module changes? Discuss even in small circles with + the module maintainer. + + * Big inter-module changes? Discuss in wider circle among module + maintainers and lead developers. Take advantage of the weekly + developer forum. + + * Ensure there is a consensus about functionality and design before + starting any implementation. + +2. **Publish your code under GNU General Public License.** + + * Use GNU General Public License header following our usual style. + Update copyright years. + + * If you include any code, style, or icons created by others, check + the original license information to make sure it can be included. + Do not forget to acknowledge the original author in the THANKS + file. When appropriate, commit in the original author's name, + and commit your changes on top of them. + + * Willing to include your code under CERN copyright? Please send + an email about this to the Lead Developer. Otherwise add a new + copyright line for your institution in the files you have + touched. + +3. **Choose good starting point to build your topical branch upon.** + + * Fixing a bug in a given version? Start from ``maint-x.y``. Name + your topical branch ``johndoe/999-bibfoo-fix-xyzzy`` using ticket + number and a short branch description. + + * Introducing a new feature? Always start from ``master``. + + * Must introduce new feature to ``maint-1.1``? Really? OK, so be + it, but make it configurable via new ``CFG_BIBFOO_XYZZY`` + configuration variable. Do not rely on its existence, since + people can upgrade/downgrade within ``v1.1.x`` point releases + frequently. Have it imported in a try/except manner and provide + fallback for older point releases. Example: + ``CFG_WEBSUBMIT_DOCUMENT_FILE_MANAGER_MISC`` in `47e4a33 + `_. + + * Introducing a new experimental feature? Start from ``next``. + +4. **Make things easily configurable and reusable by others.** + + * Need some feature that may break existing functionality used by + other production sites? Need some feature that other production + sites may want to switch off? Take care and make things + configurable to be able to easily share the code. + + * Use ``get_tag_from_name('journal title')`` vs hard-coded + ``773__p``. + + * Enable/disable custom features via role-based access control + system, e.g. action ``usebaskets``. + + * Ensure configurability of functionality via ``CFG_BIBFOO_XYZZY`` + variables. + + * Ensure configurability of code via ``pluginutils``. + + * Writing service-specific code or service-specific configuration? + Use your service-specific overlay repository. + + * Writing generally-interested code that may be reused by others? + Write against Invenio Atlantis defaults, not against local + service specific overlay assumptions and context. + +5. **Create logically separate commits for logically separate + things.** + + * Fixing a minor problem on the site of the topic branch at hand? + Create separate topical branch or at least a separate logical + commit. + + * Having a basically working version and improving upon its + performance? Maintain two separate commits. + + * Committing partially working code and fixing it later? Squash + the commits together. + + * Commit early, commit often... all the while ensuring continuous + integration principles. Make sure the topical branch is + merge-ready at almost any given moment in time, even when not + completed. Hence use of configurability upfront. + + * See `git workflow documentation on rebasing + `_ + for more. + +6. **Use sensible commit messages and stamp them with QA and ticket + directives.** + + * Describe what the patch does so that the commit message is + self-understandable without reading the code. + + * If the patch closes a ticket, use ``(closes #123)`` ticket + directive. If the patch only addresses the issue, use + ``(addresses #123)`` ticket directive. + + * If you tested your code thoroughly and stand by its perfection, + use ``Signed-off-by`` commit QA stamp. If you reviewed the code + created by others, use ``Reviewed-by`` QA stamp. Helps to get + them onto fast integration track. + + * See `git workflow documentation on commit log messages + `_ + for more. + +7. **Include test cases with the code.** + + * Always write unit and functional tests alongside coding. Helps + making sure the code runs OK on all supported platforms. Helps + speeding up the review and integration processes. Helps + understanding the code written by others by looking at their unit + test cases. + +8. **Include documentation with the code.** + + * "It's not finished until it's documented." --This may originally + have been said by Tom Limoncelli. + + * "Documentation isn't done until someone else understands + it." --Originally submitted by William S. Annis on 12jan2000. + + * "Good code is its own best documentation. As you're about to add + a comment, ask yourself, 'How can I improve the code so that this + comment isn't needed?' Improve the code and then document it to + make it even clearer."--Steve McConnell, "Code Complete" + + * "If the code and the comments disagree, then both are probably + wrong." --attributed to Norm Schryer + + * "Incorrect documentation is often worse than no + documentation." --Bertrand Meyer" + +9. **Check the overall code kwalitee.** + + * Does your branch fully implement the functionality it promises to + implement? Are all corner cases covered? E.g. citation history + graph when there are no citations? + + * Are you changing DB schema? Write an `upgrade recipe + `_. + + * Does your branch pass all our standard kwalitee tests? Have you + run `invenio-check-branch + `_ + locally? Does your branch pass Travis or Jenkins builds? + + * Name things properly. Use ``list_of_scores`` rather than + ``list2``. Use ``InvenioBibFooFatalError`` rather than + ``MyFatalError``. + + * Do not forget to sanitise all your input arguments. Escape your + HTML outputs to protect against XSS. Supply your ``run_sql()`` + arguments in a tuple to protect against SQL injection. Avoid + using ``eval()``. + + * Respect minimal requirements, e.g. write for Python-2.4 for + production ``maint-x.y`` branches that still require it. Use + Vagrant `virtual development environment + `_ + when necessary. + + * Make conditional use of optional dependencies, e.g. test + ``feedparser`` existence via ``try/except`` importing. Check + that the rest of the site still works OK without ``feedparser``. + +10. **Send the code for review and integration.** + + * Distinguish between design-review process (that should have + happened earlier, already in the first step) and the code-review + process (that happens now). + + * No API change, only bugfixes? All commits duly signed by + authors and responsible module maintainers aka integration + lieutenants? Fast integration track. + + * Possible API changes, possible user/admin feature changes? Need + to synchronise about needs and to ensure configurability and + compatibility? Slow integration track. + +11. **Help improving overall development, deployment, and operational + bandwidth.** + + * Developers can help by adopting good practices upfront early in + the process. + + * Reviewers can help by using QA stamps and fast integration + tracks in live sessions. + + * Testers can help by widening the test suite so that nightly + builds can be relied upon for deployment. + + * Administrators can help by sharing needs, requirements, + solutions, and "howto" recipes. + +12. **Share thoughts, needs, requirements, solutions, "howto" recipes + with others.** + + * Check existing list of known bugs and known feature requests for + any given module. Troubles with indexing? Go to + `Development/Modules/BibIndex + `_. + + * Did you perform some service operation such as changing your + site URL? Did you logged the several steps needed to achieve + this? Document them. `HowTo/HowToChangeSiteUrl + `_. + + * Have you tried to improve performance of some tools Invenio + relies on? Have you run experiments and obtained observations + and tips on MySQL performance? Document + them. `Tools/MySQL/Tuning + `_.