Fledge
An open source edge computing platform for industrial users
Contributing to Fledge

The project welcomes contributions of all types; documentation, code changes, new plugins, scripts, just simply reports of the way you use Fledge or suggestions of features you would like to see within Fledge.

The following is a set of guidelines for contributing to Fledge IoT project and its plugins, which are hosted in the fledge-iot Organization on GitHub.

To give us feedback or make suggestions use the fledge or fledge-help Slack Channel on LFEdge.

If you find a security vulnerability within Fledge or any of its plugins then we request that you inform us via email rather than by opening an issue in GitHub. This allows us to act on it without giving information that others might exploit. Any security vulnerability will be discussed at the project TSC and user will be informed of the need to upgrade via the Fledge Slack channel. The email address to which vulnerabilities should be reported is secur.nosp@m.ity@.nosp@m.diano.nosp@m.mic..nosp@m.com.

Pull requests

Please ask first before embarking on any significant work (e.g. implementing new features, refactoring code etc.), otherwise you risk spending a lot of time working on something that might already be underway or is unlikely to be merged into the project.

Join the fledge or fledge-help Slack channel on LFEdge. This will allow you to talk to the wider fledge community and discuss your proposed changes and get help from the maintainers when needed.

Please adhere to the coding conventions used throughout the project and limit your changes to functional rather than aesthetic changes to make it as easy as possible to review your changes. We also encourage you to comment your code changes for the same reason and for the benefit of those that come after you.

Adhering to the following process is the best way to get your work included in the project:

  1. Fork the project, clone your fork, and configure the remotes:
# Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/fledge.git
# Navigate to the newly cloned directory
cd fledge
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/fledge-iot/fledge.git
  1. If you cloned a while ago, get the latest changes of develop branch from upstream:
git checkout develop
git pull --rebase upstream develop
  1. Create a new topic branch from develop, if you are working a particular issue from the Project Jira then the convention for branch names is to use the Jira name, otherwise choose a descriptive branch name that contains your GitHub username in order to help us track the changes.
git checkout -b [topic-branch-name] upstream/develop

  1. Commit your changes in logical chunks. When you are ready to commit, make sure to write a Good Commit Message™. Use interactive rebase to group your commits into logical units of working before making them public.

    Note that every commit you make must be signed. By signing off your work you indicate that you are accepting the Developer Certificate of Origin.

    Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s.

  2. Locally merge (or rebase) the upstream development branch into your topic branch:
git pull --rebase upstream develop
  1. Push your topic branch up to your fork:
git push -u origin [topic-branch-name]
  1. Open a Pull Request with a clear title and detailed description. Also make sure always raise Pull request against develop base branch of upstream only. It must have at least one reviewer to expedite the review and also verify GitHub status checks which let you know if your commits meet the conditions set for the repository you're contributing to. GitHub Status checks are based on external processes, such as continuous integration builds, which run for each push you make to a repository. You can see the pending, passing, or failing state of status checks next to individual commits in your pull request.

Plugins

The above addresses the main Fledge repository, however plugins each have a repository of their own which contains the code for the plugin and the documentation for the plugin. If you wish to work on an existing plugin then the process is similar to that above, just replace the "fledge.git" repository with the fledge-{plugin-type}-{plugin-name}.git repository, for example

# Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/fledge-south-sinusoid.git
# Navigate to the newly cloned directory
cd fledge-south-sinusoid
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/fledge-iot/fledge-south-sinusoid.git

Repeat further steps which we mentioned here

If you wish to create a new plugin then contact the maintainers and we will create a blank base repository for you to add your code into.