EdgeX Foundry Code Contribution Process

The EdgeX Foundry (“EdgeX”) open source community welcomes all shapes and sizes of code contributions.  From simple bug fixes to new micro services, we understand that code is the life blood of any open source effort and thank you, in advance, for your contributions.

All prospective EdgeX contributors are encouraged to read our code of conduct and Contributor’s Guide:

EdgeX Charter

In addition, all EdgeX contributors must comply with the project’s charter, including the IP policy provisions contained within Section 12 of the charter.  You can find the charter here: https://www.edgexfoundry.org/about/project-charter/.

In particular, all code must be contributed to the project under the Apache-2.0 license, and exceptions require a two-thirds vote of the EdgeX Governing Board.

Large Code Contributions

When you have a significant change to suggest and want to submit your code to the EdgeX project, please follow the process diagrammed and described below.

Generally, a large or significant code contribution may be either:

  1. Significant code changes that span more than one existing EdgeX repository
  2. New large code contributions that require one or more new EdgeX repositories to be created.

  1. As a contributor (or potential contributor), contact the Working Group chairperson that is responsible for the code that would be affected by your proposed changes or additions.  Present your proposed additions or changes to the chairperson before starting your effort!  Do this so that you can:

2. After reviewing your proposal with the appropriate working group chair and getting their consent, start work on your implementation.  Develop your code and either:

Inform the Working Group chairperson when your proposed code has been uploaded to eval-GitHub space and is ready for review. 

3. Once your code has been submitted to the eval-GitHub space and/or new repository as needed, the appropriate Working Group chairperson will notify the EdgeX Technical Steering Committee’s (TSC) chairperson of the large contribution.

4. The TSC chairperson will form an ad-hoc committee to review your contribution.  The ad-hoc committee will usually consist of the appropriate working group chairs and other members of the community at large that have insights on the current state of EdgeX, the roadmap for EdgeX, as well technical background in the area of your contribution.  The TSC chairperson will also set a tentative completion date for the review to be conducted (typically less than 2 weeks depending on the nature/size of the contribution).  The ad-hoc committee is tasked with evaluating your contribution and providing comment/feedback to the TSC chair on the following:

4b. The ad-hoc committee will review the contribution for general EdgeX use.  However, the committee may find the contribution (or a portion of the contribution) would better exist as a project or addition to a vertical working group solution.  Therefore, the ad-hoc committee may pass the contribution (or a portion of the contribution) on to the appropriate vertical working group chairperson where the same evaluation would occur, but in light of any EdgeX vertical solution.

Special note for device service contributions:  the device service working group chair has documented a review process for how new device services will be examined.

IMPORTANT PROCESS NOTE:  if a contributor does not begin the contribution process by working with the appropriate Working Group chairperson and getting their feedback (i.e. the contributor skips step #1 above), then the contribution can still be made and this process starts at step #2.  However, the evaluation of the contribution, as described in this step #4, will generally take longer and could result in many more exchanges with the contributor to understand where it fits in the overall architecture, how it works, etc.

5. Once the review is completed by the ad-hoc committee (or vertical solution group – 5b), a report of the evaluation is provided to the TSC chairperson along with a recommendation to accept, reject or request additional input from the contributor.  The request for additional input may be a request of the contributor to address deficiencies, problems identified, etc. and resubmit the contribution for another evaluation.

6. In some cases, based on the review of the contribution and license or other content concerns found in the contribution (i.e. code found in the contribution appears to be from another non-attributed source), the TSC chairperson may seek guidance from the Governing Board, or any committee set up for such purpose by the Governing Board, as to whether the contribution creates issues with regard to the Apache-2.0 license.  Legal concerns must be addressed before the contribution can be accepted and may result in rejection of a contribution.

7. The TSC chairperson will supply the ad-hoc committee’s review and recommendation on the contribution to the TSC membership and ask for a vote to accept or reject the contribution.  On a majority vote to accept, the TSC chairperson will inform the appropriate working group chairperson to authorize the code to be moved from the eval-GitHub to the EdgeX GitHub (for new repositories), accept the PR (on work to existing repositories), and work with DevOps to incorporate the contribution into the appropriate continuous integration processes.  If the vote is to reject the contribution, the chairperson will ask the DevOps chairperson to remove the contribution from the eval-GitHub.  The contributor will be informed by the TSC chairperson of either result as soon as possible.

Small Code Contributions

The process for submitting cosmetic code clean up, bug fixes, or smaller/minor changes can be done by submitting Pull Requests (PR) through GitHub on existing, affected project repositories.  While somewhat arbitrary and subject to waiver, code contributions larger than 500 lines of code are considered large (not small or medium).  The chairperson of the EdgeX Working Group (and their designated committers/maintainers) responsible for the code repository in which a change is made will review the PR and either make requests for changes or accept the PR and bring a contribution into the EdgeX repo’s master branch.

The list of repositories associated to the various Working Groups is here:  https://wiki.edgexfoundry.org/display/FA/Technical+Work+in+the+EdgeX+Foundry+Project#TechnicalWorkintheEdgeXFoundryProject-AppointmentofCommittersandMaintainers

Small code contributions must still comply with the EdgeX charter.  In addition, small code contributions should follow the procedure for large code contributions if the answer to any of the following questions is ‘yes’:

Large versus Small Contribution

Large contributions are those that meet any of the following criteria.

Small/Medium contributions typically

If you are not sure if your contribution qualifies as small or large, contact the chairperson of the Working Group with responsibility of the affected repository and seek their guidance.  You can reach a Working Group chairperson through the appropriate Slack channel, or the email reflectors.

If you are not sure of which Working Group chairperson to contact, submit your request for assistance to the #general Slack channel (https://edgexfoundry.slack.com/messages/CE4MHUBTM) or TSC mail list (https://lists.edgexfoundry.org/mailman/listinfo/edgex-tsc).