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, this page has been set up to help guide you through some information you need to know before working on and contributing code to the EdgeX project.
We have recently migrated all of the individual go services to live in a mono-repo at https://github.com/edgexfoundry/edgex-go The previous single go service repositories still exist but are in an archived "read-only" state. All go work should be completed against the mono-repo.
Code Style Guides
The EdgeX project technical community has adopted the Google Style Guides for all programming languages. 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.
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.
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:
- For Notepad++ (v7.5.1) go to "Settings > Preferences > New Document/Default Directory" then select "Unix/OSX"
Go programs are often comprised of packages from many different sources. Each one of these sources are pulled in from the
GOPATH or from the standard library. With Go 1.5 a new method to discover go packages was released. Nothing has been changed or added to the go language or the go compilers. Packages must still reside in
GOPATH. However, if a package or a parent folder of a package contains folder named
vendor it will be searched for dependencies using the
vendor folder as an import path root. There are many tools that use the vendor folder today. Glide and govendor are two that are popular. The EdgeX Go community has chosen to use Glide as its vendoring tool of choice and will use this tool to check dependencies when code gets checked into source control?
EdgeX current uses and supports Go Lang version 1.9 or better.
The following list of Go Lang libraries are used in various EdgeX micro services. While reluctant to establish approval lists, developers are "encouraged" to continue using these libraries in their EdgeX Go development.
- go-yaml - converting YAML files into data models (device profile)
- gorilla or bone - router for API requests
- hashicorp/consul - official Consul library for Golang
- mitchellh/home-dir - get the home directory of the user
- ventu-io or Uber's Zap - logging library (used to log to stdout)
- robfig/cron - used to parse cron expressions
- gopkg.in/mgo.v2 - Connect to and interact with Mongo DB
The following list of Go Lang libraries or projects are not used in EdgeX micro services. While EdgeX does not forbid their use, developers are strongly "discouraged" from using these as they have been found to create issues in the community.
- Go Kit- very opinionated in its patterns and considered to add undo complexity to a Go project
As a potential contributor of code to the project, you are highly encouraged to read the Project 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 http://elinux.org/Developer_Certificate_Of_Origin for more details.
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)
Existing source from the project can be used to exemplify this header.
EdgeX uses GitHub Issues to submit and track bugs.
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 RocketChat for initial feedback before submitting the issue in GitHub Issues .
Versioning and Versioning Scheme
EdgeX has adopted a significance-based approach to versioning. This versus a semantic versioning approach (see reference #1 below).
Instead of tightly coupling the version number updates to changes in the REST API(s) exposed by a microservice, EdgeX updates the version number when there has been a significance in the microservice as a whole. Similar to the semantic version scheme, the significance of change scheme also uses a three-part version with numbers representing major, minor, and patch changes. The latter can be left off until actually needed.
A microservice starts its life as version 0.1, and each new release bumps the second number. The move from 0.x to 1.x in EdgeX signifies that the microservice is transitioning from a development to a production quality release. The decision to make the transition to a production release rests with the responsible Working Group chair with approval from the EdgeX Technical Steering Committee. Further jumps in the major number typically indicate major new releases of the project which *could* signify API breakage, but could also signify major new functionality as well.
If/when a maintenance release of a particular microservice is warranted, a third number gets introduced. So, if 0.5 is released, and a serious bug is found and fixed immediately, 0.5.1 could be released right away, while development continues as normal on master toward 0.6. For example, you can see the historical version numbers used by the bluez project (Linux Bluetooth stack) (see reference #2 below) are just major.minor, as they usually rely on distros to release maintenance releases. An example of a project that uses three-digit versions is snapd (see reference #3 below), the daemon at the heart of the snap ecosystem.