APPENDIX E: OLE Contribution Requirements

tracker

Last updated September 27, 2014.

Tested and formalized by Atlanta Kuali Community Workshop, April 2014

Adam Constabaris, NCSU +1
Dale Arntson, Chicago +1
John Pillans, IU +1
Grover McKenzie, Penn +1
Michelle Suranofsky, Lehigh +1
Jeff Fleming, Duke +1
David Lacy, Villanova +1
Shian Chang, UM +1

The JIRAs to be used for “testing” this process will be identified and added to this section.

These are the deliverables required for a source code contribution to the OLE codebase.

Any contribution to the OLE project must go through the standard approval process through the OLE Functional Council and scheduled for a release, regardless of issue type and managed through the OLE Project Manager.

  • Enhancement Process
  • Design Review
  • Code Review
  • Documentation
  • Unit Tests
  • Bug Fix Process
  • Code Review
  • Unit Tests (as needed)
  • Documentation (as needed)
  • Documentation
  • Documentation files or patch files for DocBook
  • Conversion to DocBook format is requested
  • Considerations for Contribution Review

Functional

  • Are the functional requirements and acceptance criteria documented somewhere so we know how it’s supposed to work?
  • What are the known issues gaps, bugs, etc.?
  • Does the contributor have a Roadmap for delivered functionality?
  • Is the intention for this to be maintained as core OLE?
  • How will the contributors be involved? Consider continuing interest, maintenance, expectations and desires.

Technical

  • Is the architecture documented?
  • What technologies are being used (KIM, KNS, KRAD, other libraries, and why?)
  • What automated tests are there? Any gaps in testing? Will manual testing be required?
  • What access would we have to the original team for questions?
  • Is the contributing team available to make updates as needed from code review?
  • Can the documentation be delivered in DocBook format?

The Contribution Process

1) Contribution Proposal

  • The first step in contributing to OLE is to create an issue in JIRA per the following guidelines. If an existing JIRA exists in the OLE Project queue these can be linked. The contribution will remain in OLE Feedback Queue until the contribution is adopted for integration to OLE.
  • Enhancements should be added to OLE Feedback Queue.
  • Attach all requirements or design documents to the JIRA.
  • Bug fixes should be added to the OLE Feedback Queue.
  • If possible, add a patch file to the JIRA.
  • If a Kuali partner institution is interested in contributing a large number of bug fixes, then contact the OLE Project Manager to see if we can arrange an easier way to get your fixes directly into the codebase.
  • Code Share (these are items that someone has developed and would like to make available to the community but not in the baseline code)
    • not a free-for-all (will require some sort of stewardship)
    • may be in language not suitable for inclusion in OLE core
    • may be a “hit and run” contribution (contributor will not be around to handle questions/enhancements)
    • may have a license/license requirements incompatible with ECL 2.0
    • may be useful but have incomplete/fuzzy requirements and acceptance criteria
    • there is a space in Kuali Github for contributions like this for some projects.
    • should involve documentation of criteria for these contributions (contact info, baseline requirements, etc.) 

2) Project Review

  • Review planned 3rd party licenses to ensure compatibility with ECL 2.0
  • See Kuali Foundation 3rd Party Licenses page
  • Enhancements are reviewed by the SME group of the appropriate module:
  • SME group reviews the new contributions.
  • New contributions are escalated by the SME group to the Functional and/or Technical Council for scoping or further analysis.
  • Development Managers review for integration to source code.
  • Bug fixes are reviewed by the QA Manager/Lead SME for placement.
  • Development Managers review the bug fixes for integration to source code.
  • Once an OLE Feedback Queue JIRA has been accepted as functionally to be included in a version of OLE, it is moved to the OLE Queue (Main) for work.

3) Contribution Development & Code Review

  • Ideally, the contribution development and code review process will be an iterative process to help ensure that the contribution can easily be incorporated into the core code.
  • Determine if the code is developed on a branch of the core OLE code.
  • Contributors develop the code.
  • Once code is complete, an OLE Development Manager will coordinate a code review.
  • If the enhancement involved DB changes, changes will be reviewed for compliance in a similar nature to the Kuali Rice Database Change and Migration Policy.
  • QA Lead will conduct a code review of the tests and ensure that your code is in compliance in a similar nature to the Kuali Rice Unit Testing and Build Policy.
  • Documentation Lead will conduct a review of the documentation to ensure documentation is complete in a similar nature to the Kuali Rice Documentation Policy.
  • Creating regression/functional acceptance tests is strongly encouraged and communication with the OLE QA team should be well under way. Contributions should be regression tested using the OLE QA suite.
  • We recommend that your code change has been exercised in an OLE testing environment.
  • There will probably be some changes recommended during the reviews before the contribution can be accepted. Any objections that come up during the review process must be resolved.
  • Will need to develop a style/conventions guide similar to/derived from the OLE Kuali Coding Conventions and Java Style Guidelines
  • The Code Steward is the role in the project which has the authority to review and accept the code. If a dispute arises, the Technical Council will vote.

4) Contribution Final Acceptance

  • Code (including tests) are merged back into the core OLE code.
  • Documentation is incorporated into core documentation code.

Checking In Contributions

  • Any time you check in code to the OLE project, you must specify the *associated JIRA key (e.g. OLE-XXX)* for the corresponding work that the check-in is related to in addition to a normal svn check-in comment.

Tips on How to Develop a Contribution Properly

Other Ways to Contribute

  • Code contributions are not the only things we might seek from project members or outside organizations, documentation and testing should also be accepted.