Contributing patches

Contributing patches

Congratulations! Most likey, you are reading this page because your work on ODPi resulted in code changes. Now you have to figure out how to integrate those patches into ODPi reference implementation and we're here to help you with that.

ODPi reference implementation is integrating together software components produced by various upstream projects (so far all of them come from Apache Software Foundation but that may change). Even the integration framework itself is an Apache Project: Apache Bigtop. All of these upstream projects are being tracked in ODPi specific repositories available under the https://github.com/odpi organization. While this setup certainly makes it possible for ODPi to accommodate one-off patches our strong preference is for making sure that we push the changes into the upstream projects as soon as possible.

Keep in mind that even the test cases from the ODPi validation testsuite (something that is very specific to the ODPi efforts) have a non-0 chance of being accepted into Apache Bigtop. Thus, always ask yourself a question of what's a natural place upstream for your code to reside. In a few cases the answer will be that there's no such project and then the patches have to stay at ODPi level.

The "patch flow" workflow

If you have a lot of experience with ODPi and upstream projects, some of the following steps could be skipped, but for the benefits of new ODPi members and contributors this is how the overall workflow looks like:

1. Start with building a patched version of ODPi reference implementation hitting the repos and branches you fork from ODPi organization (you can take a look at our Jenkins jobs definitions for understanding how the reference implementation is supposed to be built).
2. For all the repos that need to be patched submit a PR via GitHub against the ODPi repos
3. Update ODPi JIRAs with pointers to all the required PRs
4. Start investigating if the changes you made are available in newer versions of the components you had to patch (this may be a good step #0 actually ;-)). Update ODPi JIRA with your findings.
5. If newer versions of the patched component have a change already available, investigate how easy it would be to backport it into the current ODPi version vs. bumping the version of the component to the version that has the patch available. This may require an email exchange on the ODPi mailing list and/or upstream component one. Regardless of the outcome of upgrade vs. backport discussion make sure to update the OPDi JIRA with pointers to upstream JIRAs that dealt with the issue.
6. If newer version of the patched component suffers from the same problem start by filing an upstream JIRA, providing your patch and working with an upstream community to get the patch accepted. If you need help don't hesitate to ask on the ODPi technical mailing list. Also, make sure to always update OPDi JIRA with pointer to upstream JIRAs tracking the patch integration.

The ODPi reference implementation update

If all the rights steps described above have been taken you should expect your PRs to be merged into the ODPi reference implementation repos. Always make sure to either take exact commits from the upstream repos that fix the issue OR to provide as much information as possible in the commit message linking the change back to the upstream JIRAs.