Contributor's Guide

Owned by jimastata
Last updated: Jan 25, 2023 by James Butcher
5 min read

Welcome!  We really hope you are here because you are seriously thinking about adding to the EdgeX Foundry IoT platform.  We can't wait to receive your contribution!  Before you make your first submission, the pages in this part of the Wiki have been set up to help guide you through some information you need to know before working on and contributing code to the EdgeX project.

Code Style Guides

The EdgeX project technical community has adopted the Google Style Guides for all programming languages.  The EdgeX project does use checkstyles during the build process.  So code that does not conform to the style guide will result in a request by the project to address issues before being accepted.

Go Lang Code Style Guides

For style, the projects asks all Go Lang developers to use 'gofmt' prior to committing any code to ensure the style guide is always followed.  Developers are also encouraged to use 'go vet', which is a static code analyzer that can catch unused code, common mistakes, etc.

While also not required, EdgeX Go Lang developers are encouraged to read (and re-read) Effective Go.  This web site can help improve the quality, consistency and style of your Go code.

Some important conventions already provided in the guidelines and reading material include:

  • Regular file names are lower case, short, and without any sort of underscore or space. Generally, file names follow the same convention as package names. See the Package Names section of Effective Go.
  • File names that begin with "." or "_" are ignored by the go tool
  • Files with the suffix _test.go are only compiled and run by the go test tool.
  • Files with os and architecture specific suffixes automatically follow those same constraints, e.g.  name_linux.go will only build on linux, name_amd64.go will only build on amd64.

C Code Style Guides

All code should comply with either the C99 or C11 versions of the C language specification.

Line Feeds

Line endings in code files are different for *nix versus Windows.  In *nix, lines end with “\n”.  In Windows, lines end with “\r\n” (carriage return, line feed).  This creates issues when pulling/working with code created in different environments.

The *nix line feed is the desired line ending for EdgeX Foundry source code.  Windows developers need to configure tools to use and apply the appropriate line endings.  Thanks to Gorka Garcia from Cavium, here are some examples of how to configure some popular tools to deal with this issue.

  • For Eclipse (Version: Oxygen.2 Release (4.7.2)), go to “Window > Preferences > General > Workspace” settings and find “New text file line delimiter” and set it to “Other: Unix”, this will set the line endings for new files. There is also  “File > Convert Line Delimiters To > Unix” option for converting files already with windows line endings.
  • For Microsoft Visual Studio Code (v1.19.2) you need to add the following to the user configurations:

    "files.eol": "\n"

  • For Notepad++ (v7.5.1) go to "Settings > Preferences > New Document/Default Directory" then select "Unix/OSX"

Submission DCO

As a potential contributor of code to the project, you are highly encouraged to read the Technical Charter and in particular note section 12 - Intellectual Property Policy.  Contributors are advised to understand that submitting code to the project indicates you agree with the the Developer Certificate of Origin. See the Committing Code Code Guidelines for details on how to sign your code contributions to indicate your agreement with the DCO. See http://elinux.org/Developer_Certificate_Of_Origin for a description of how the Linux kernel implements its DCO.

You can add the DCO signoff to your Git commit by adding the --signoff flag to your git command.

If you've already committed your code to your local branch without the DCO signoff, you can add it with the following commands:

git reset --soft HEAD^
git commit --signoff -m "<your original commit message>"

If you've already pushed your code branch to Github and created a pull request, you will need to forcibly override that branch:

git push --force <your remote> <your branch>

Submission License and Copyrights

All code submitted to the project must be made available under Apache License, Version 2.0.

A copyright header should appear at the top of all project artifacts (code files, configuration files, documentation, etc.).  The copyright header should contain:

  • Apache License 2.0 statement
  • Copyright of the contributing entity (person or corporation)

Note: when subsequent contributors make substantive changes to a file they may also optionally add a copyright line to the header for themselves (person or corporation), but should preserve existing copyright statements and license.

Existing source from the project can be used to exemplify this header.

Example Project Artifact Header 
/*******************************************************************************
 * Copyright 2016-2017 Dell Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 *
 *******************************************************************************/

Bug Tracking

EdgeX uses GitHub Issues to submit and track bugs. 

Reporting Issues

This is a great way to contribute. Before reporting an issue, please review current open issues to see if there are any matches.  To see the current list of EdgeX issues, go to the project's GitHub site and click on the Issue link at the top of the page.

How to Report an Issue

In the GitHub repository, anyone can create a new issue for any of the project's repositories - no sign in is required!  Locate the repository you believe contains the bug.  Then click on the Issues tab of the repository, and then click on the green "New Issue" button to create and submit a new bug.

When reporting an issue, please provide as much detail as possible about how to reproduce it.  Details are key, please include the following:

  • OS version
  • EdgeX version
  • Environment details (virtual, physical, configuration details etc.)
  • Steps to reproduce
  • Actual results
  • Expected results

If you would like, you could also bring up the issue on the main GitHub discussion boards for initial feedback before submitting the issue in GitHub Issues .

Code Styles and Checkstyles

The EdgeX project has adopted the Google Style Guides (https://github.com/google/styleguide) for use in all EdgeX coding.

In support, of keeping the styles applied to projects, developers are encouraged to use the tools at their disposal to apply the styles to their code and to address issues before checking code into the project’s repositories.