8.3 KiB

Raw Blame History

Contributing to Mainflux

Thank you for your interest in Mainflux and wish to contribute!

The following is a set of guidelines for contributing to Mainflux and its libraries, which are hosted in the Mainflux Organization on GitHub. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

This project adheres to the Contributor Covenant 1.2. By participating, you are expected to uphold this code. Please report unacceptable behavior to abuse@mainflux.com.

Submitting Issues
Pull Requests
Merge Approval
Documentation Styleguide

Submitting Issues

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!

Guidelines for bug reports:

Use the GitHub issue search — check if the issue has already been reported.
Check if the issue has been fixed — try to reproduce it using the latest master or development branch in the repository.
Isolate the problem — ideally create a reduced test case and a live example.

A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What browser(s) and OS experience the problem? What would you expect to be the outcome? All these details will help people to fix any potential bugs.

Please setup a profile picture to make yourself recognizable and so we can all get to know each other better.

Pull requests

Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Please adhere to the coding conventions used throughout a project (indentation, accurate comments, etc.) and any other requirements (such as test coverage).

Follow the JavaScript styleguide
Follow the NodeJS styleguide
Document new code based on the Documentation Styleguide
End files with a newline
Place requires in the following order:
- Built in Node Modules (such as path)
- Built in Mainflux Modules (such as coreflux)
- Local Modules (using relative paths)

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

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>/mainflux.git

# Navigate to the newly cloned directory
cd mainflux

# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/Mainflux/mainflux.git

If you cloned a while ago, get the latest changes from upstream:
```
git checkout master
git pull upstream master
```
Create a new topic branch (off the main project development branch) to contain your feature, change, or fix.

This separate branch for each changeset you want us to pull in should contain either the issue number in the branch name or an indication of what the feature is.

If you're working on an issue in the Issues list for the main Mainflux repo, use the naming convention mainflux-[issue-num] for your branch name to help us keep track of what your patch actually fixes:
```
# List your current branches
git branch

# Create a new branch called mainflux-[issue-num]
git branch mainflux-[issue-num]

# Switch to the new brach
git checkout mainflux-[issue-num]
```
or in one go:
```
git checkout -b mainflux-[issue-num]
```
Commit your changes in logical chunks. Please adhere to these git commit message guidelines or your code is unlikely be merged into the main project. Use Git's interactive rebase feature to tidy up your commits before making them public.

Squash your commits into logical units of work using git rebase -i and git push -f. A logical unit of work is a consistent set of patches that should be reviewed together: for example, upgrading the version of a vendored dependency and taking advantage of its now available new feature constitute two separate units of work. Implementing a new function and calling it in another file constitute a single logical unit of work. The very high majority of submissions should have a single commit, so if in doubt: squash down to one.

After every commit, make sure the test suite passes. Include documentation changes in the same pull request so that a revert would remove all traces of the feature or fix.
Locally merge (or rebase) the upstream development branch into your topic branch:
```
# Get the latest code from upstream
git fetch upstream

# Verigy that you are on the master branch
git checkout master

# Perform the merge
git merge upstream/master
```
or in one go:
```
git pull [--rebase] upstream master
```
If there are no conflict, you are all set, if there are some you can resolve them by hand (by editing the conflicting files), or with
```
git mergetool
```
which will fire up your favourite merger to do a 3-ways merge.

3-ways means you will have your local file on your left, the remote file on your right, and the file in the middle is the conflicted one, which you need to solve.

A nice 3-ways merger makes this process very easy, and merging could be fun. To see what you have currently installed just do git mergetool
Push your topic branch up to your fork:
```
git push origin mainflux-[issue-num]
```
Open a Pull Request with a clear title and description.
Sign off your pull request The sign-off is a simple line at the end of the explanation for the patch.

By signing-off you indicate that you are accepting the Developer Certificate Of Origin. For now, we are using them same DCO as Linux kernel developers are using.

Your signature certifies that you wrote the patch or otherwise have the right to pass it on as an open-source patch.

You can simply make a comment something like:

Signed-off-by: John Doe <john.doe@hisdomain.com>

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.

IMPORTANT: By submitting a patch, you agree to allow the project owners to license your work under the terms of the Apache License, Version 2.0.

Merge approval

Mainflux maintainers use LGTM (Looks Good To Me), or sometimes ACK (Acknowledged) or simple "+1", in comments on the code review to indicate acceptance.

A change requires LGTMs from an absolute majority of the maintainers of each component affected. For example, if a change affects docs/ and app/, it needs an absolute majority from the maintainers of docs/ AND, separately, an absolute majority of the maintainers of app/.

For more details, see the MAINTAINERS page.

Documentation Styleguide

Use Markdown
Use Doxygen documenting styleguide
Specifficaly, use JavaDoc flavor
See Atomthreads project for fantastic example of code commenting

8.3 KiB Raw Blame History