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:

• Code of Conduct:  https://www.edgexfoundry.org/about/code-of-conduct/
• Contributors Guide:  https://wiki.edgexfoundry.org/display/FA/Contributor%27s+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:

• • Get information on other work that may be ongoing so as to avoid conflicts or duplication of effort when the actual code is developed and then submitted.
  • Understand the longer term technical roadmap for the areas of the platform that will be affected by your proposed change.   You may find your suggested change will soon be overcome by changes or additions that will be put in place in the near future by others in the community.
  • Elicit feedback from the current architects and implementation team on your proposed change(s) or addition(s).  This will help identify potential issues or conflicts with the existing architecture or design moving forward.  It may also provide some valuable lessons learned and reveal information about prior large contributions, and how/why they succeeded or failed.
  • Gain quicker review and adjudication of your contribution once implemented and submitted (see step 4), due to the working group already having familiarity with your changes and implementation plans.

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:

• • For new code that needs a new repository, push your new code to the EdgeX evaluation GitHub project space (github.com/edgexfoundry-holding).  You will need to contact the EdgeX DevOps chairperson in order to get a repository created in the eval-GitHub to submit the contribution (James Gregg).
  • For code to be added to an existing repository, make the necessary Pull Requests (PR) through GitHub on the affected project repositories.

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:

• • Architectural fit:  does the contribution live up to the EdgeX architectural tenets and fit within the existing framework?  If it does not the committee may comment for TSC consideration whether they believe the underlying architecture is a superior architecture and one that may need to be explored by the TSC and project overall.
  • Quality of the code:  does the contribution adhere to good industry and EdgeX required programming practices and standards (see https://wiki.edgexfoundry.org/display/FA/Contributor%27s+Guide for the EdgeX contributor guidelines)?  Does the contribution actually build and run as is or will it require a lot of additional work be done?  Does the contribution and run on Intel and Arm platforms?
  • Quality and depth of documentation:  is the code adequately commented, is there sufficient documentation to explain what the contribution does, how it works and how to use it (from a novice user point of view)?
  • Test coverage:  does the code base contain adequate unit tests, integration tests, blackbox test additions, etc.?  Additions, via PR may need to be submitted for test repositories (such as the blackbox tests repository) to satisfy this need.
  • Performance impact:  does the contribution negatively impact the EdgeX footprint, CPU usage, memory usage, start up time, or other performance characteristic?  The negative impact is relative, but any significant impact to performance would need to carefully considered.
  • DevOps impact: does the contribution require special devOps, continuous integration or deployment aspects of EdgeX.  If so, what is the resource requirements to incorporate the contribution into the EdgeX devOps, CI, etc. processes?  Does it have Dockerfiles (amd64 and arm64) and other devOps artifacts to incorporate into the EdgeX DevOp environment with little or no changes? 
  • Long-term maintenance:  what are the long-term implications of accepting the contribution on the EdgeX community?  Are there sufficient committers, maintainers, contributors that are in the community (or joining the community with the addition) to manage the contribution in the future?
  • Roadmap priority: does the contribution fulfill an existing EdgeX roadmap need/item?  If it does not, does accepting the contribution meet an anticipated community or user need that makes maintaining the contribution long term a good investment for EdgeX community time?
  • Dependency analysis: does the contribution require upstream components, and, if so, are they all under the Apache-2.0 license?
  • Does the contribution represent a fork of an upstream project? If so, why is it necessary to fork the upstream project, and do the project leads commit to update the contribution with upstream security patches and bug fixes?
  • License requirements:  is the contribution done under the Apache-2.0 license, does it contain all the appropriate license files, headers in the source files, attribution files where necessary? Are all the commits properly signed-off?

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’:

• Does the code leverage upstream components not licensed under Apache-2.0?
• Is the code contributed under any license other than Apache-2.0?

Large versus Small Contribution

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

• Change the application architecture
• Require new repositories be added to the EdgeX Foundry Project on GitHub
• Change, add or remove code across multiple repositories

Small/Medium contributions typically

• Do not change the architecture in any way
• Do not require the addition or removal of any project repository
• Affect only a single (or few) repository

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.

• Slack: https://edgexfoundry.slack.com/
• Email Reflector Lists:  https://lists.edgexfoundry.org/mailman/listinfo

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).