OrgGo/Mainflux.mainflux
1
0
Fork 0
mirror of https://github.com/mainflux/mainflux.git synced 2025-04-29 13:49:28 +08:00
Code Issues Projects Releases Wiki Activity

Fix contributing guide

Browse Source 
Signed-off-by: Dejan Mijic <dejan@mainflux.com>
This commit is contained in:
Dejan Mijic 2017-09-23 13:43:23 +02:00
parent 4132a5c017
commit 40d4dd5f2d
No known key found for this signature in database
GPG Key ID: 35CD2D6AB811FEFC
4 changed files with 90 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/CODEOWNERS vendored Normal file
View File

@ -0,0 +1 @@
* @mainflux/maintainers

30
.github/ISSUE_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,30 @@
<!--
The GitHub issue tracker is for bug reports and feature requests. General support can be found at
the following locations:
- Google group - https://groups.google.com/forum/#!forum/mainflux
- Gitter - https://gitter.im/mainflux/mainflux
-->
**FEATURE REQUEST**
1. Is there an open issue addressing this request? If it does, please add a "+1" reaction to the
existing issue, otherwise proceed to step 2.
2. Describe the feature you are requesting, as well as the possible use case(s) for it.
3. Indicate the importance of this feature to you (must-have, should-have, nice-to-have).
**BUG REPORT**
1. What were you trying to achieve?
2. What are the expected results?
3. What are the received results?
4. What are the steps to reproduce the issue?
5. In what environment did you encounter the issue?
6. Additional information you deem important:

176
CONTRIBUTING.md
View File

@ -1,61 +1,50 @@
# Contributing to Mainflux # 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](https://github.com/mainflux) on GitHub.
The following is a set of guidelines for contributing to Mainflux and its libraries,
which are hosted in the [Mainflux Organization](https://github.com/Mainflux) 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](http://contributor-covenant.org/version/1/2/0). This project adheres to the [Contributor Covenant 1.2](http://contributor-covenant.org/version/1/2/0).
By participating, you are expected to uphold this code. Please report unacceptable behavior to [abuse@mainflux.com](mailto:abuse@mainflux.com). By participating, you are expected to uphold this code. Please report unacceptable behavior to
[abuse@mainflux.com](mailto:abuse@mainflux.com).
#### Table Of Contents ## Reporting issues
* [Submitting Issues](#submitting-issues) Reporting issues is a great way to contribute to the project. We always appreciate a well-written,
* [Pull Requests](#pull-requests) thorough bug reports.
* [Merge Approval](#merge-approval)
* [Documentation Styleguide](#documentation-styleguide)
## Submitting Issues Prior to raising a new issue, check out [our issue
list](https://github.com/mainflux/mainflux/issues) to determine whether it already include the
problem you are facing.
A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful - thank you! A good bug report shouldn't leave others needing to chase you up for more information. Please try to
be as detailed as possible. The following questions might serve as a template for writing a detailed
reports:
Guidelines for bug reports: - What were you trying to achieve?
- What are the expected results?
- Use the GitHub issue search — check if the issue has already been reported. - What are the received results?
- Check if the issue has been fixed — try to reproduce it using the latest master or development branch in the repository. - What are the steps to reproduce the issue?
- Isolate the problem — ideally create a reduced test case and a live example. - In what environment did you encounter the issue?
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](https://help.github.com/articles/how-do-i-set-up-my-profile-picture)
to make yourself recognizable and so we can all get to know each other better.
## Pull requests ## Pull requests
Good pull requests - patches, improvements, new features - are a fantastic Good pull requests (e.g. patches, improvements, new features) are a fantastic help. They should
help. They should remain focused in scope and avoid containing unrelated remain focused in scope and avoid containing unrelated commits.
commits.
**Please ask first** before embarking on any significant pull request (e.g. **Please ask first** before embarking any significant pull request (e.g. implementing new features,
implementing features, refactoring code, porting to a different language), refactoring code etc.), otherwise you risk spending a lot of time working on something that the
otherwise you risk spending a lot of time working on something that the maintainers might not want to merge into the project.
project's developers might not want to merge into the project.
Please adhere to the coding conventions used throughout a project (indentation, Please adhere to the coding conventions used throughout the project. If in doubt, consult the
accurate comments, etc.) and any other requirements (such as test coverage). following style guides:
* Follow the [EffectiveGo](https://golang.org/doc/effective_go.html) styleguide - [Effective Go](https://golang.org/doc/effective_go.html)
* Follow the [Google's JavaScript styleguide](https://google.github.io/styleguide/jsguide.html) - [Google's JavaScript styleguide](https://google.github.io/styleguide/jsguide.html)
* Document new code based on the [Documentation Styleguide](#documentation-styleguide)
* End files with a newline
Adhering to the following process is the best way to get your work Adhering to the following process is the best way to get your work included in the project:
included in the project:
1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your 1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork, and configure
fork, and configure the remotes: the remotes:
```bash ```bash
# Clone your fork of the repo into the current directory # Clone your fork of the repo into the current directory
@ -65,7 +54,7 @@ included in the project:
cd mainflux cd mainflux
# Assign the original repo to a remote called "upstream" # Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/Mainflux/mainflux.git git remote add upstream https://github.com/mainflux/mainflux.git
``` ```
2. If you cloned a while ago, get the latest changes from upstream: 2. If you cloned a while ago, get the latest changes from upstream:
@ -75,71 +64,29 @@ included in the project:
git pull upstream master git pull upstream master
``` ```
3. Create a new topic branch (off the main project development branch) to 3. Create a new topic branch from `master` using the naming convention `mainflux-[issue-num]` to
contain your feature, change, or fix. help us keep track of your contribution scope:
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](https://github.com/Mainflux/mainflux/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:
```bash
# 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:
```bash ```bash
git checkout -b mainflux-[issue-num] git checkout -b mainflux-[issue-num]
``` ```
4. Commit your changes in logical chunks. Please adhere to these [git commit 4. Commit your changes in logical chunks. When you are ready to commit, make sure to write a Good
message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) Commit Message™. Consult the [https://github.com/erlang/otp/wiki/Writing-good-commit-messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
or your code is unlikely be merged into the main project. Use Git's if you're not sure what constitutes a Good Commit Message™. Use [interactive rebase](https://help.github.com/articles/about-git-rebase)
[interactive rebase](https://help.github.com/articles/about-git-rebase/) to group your commits into logical units of working before making them public.
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`. Note that every commit you make must be signed. By signing off your work you indicate that you
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. are accepting the [Developer Certificate of Origin](https://developercertificate.org/).
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. 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`.
5. Locally merge (or rebase) the upstream development branch into your topic branch: 5. Locally merge (or rebase) the upstream development branch into your topic branch:
```bash
# 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:
```bash ```bash
git pull [--rebase] upstream master 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
```bash
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`
6. Push your topic branch up to your fork: 6. Push your topic branch up to your fork:
@ -147,42 +94,5 @@ included in the project:
git push origin mainflux-[issue-num] git push origin mainflux-[issue-num]
``` ```
7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) 7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title
with a clear title and description. and detailed description.
8. 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](http://elinux.org/Developer_Certificate_Of_Origin) 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:
```bash
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](LICENSE).
## 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](MAINTAINERS) page.
## Documentation Styleguide
* Use [Markdown](https://daringfireball.net/projects/markdown) for READMEs and similar
* Use [Godoc](https://blog.golang.org/godoc-documenting-go-code) for in-code documentation

35
README.md
View File

@ -7,31 +7,20 @@
![banner][banner] ![banner][banner]
Mainflux is modern, massively-scalable, highly-secured open source and patent-free IoT cloud Mainflux is modern, scalable, secure open source and patent-free IoT cloud platform written in Go.
platform written in Go.
It allows device, user and application connections over various network protocols, like HTTP, MQTT, It accepts user, device, and application connections over various network protocols (i.e. HTTP,
WebSocket, and CoAP, making a seamless bridge between them. It is used as the IoT middleware for MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the IoT middleware
building complex IoT solutions. for building complex IoT solutions.
For more details, check out the [official documentation][docs]. For more details, check out the [official documentation][docs].
## Features ## Features
An extensive (and incomplete) list of features includes: - Protocol bridging (i.e. HTTP, MQTT, WebSocket, CoAP)
- Responsive and scalable microservice architecture - Device management and provisioning
- Set of clean APIs: HTTP RESTful, MQTT, WebSocket and CoAP - Fine-grained access control
- SDK - set of client libraries for many HW platforms in several programming languages: C/C++, JavaScript, Go and Python - Container-based deployment using [Docker][docker]
- Device management and provisioning and OTA FW updates
- Highly secured connections via TLS and DTLS
- Enhanced and fine-grained security with Access Control Lists
- Easy deployment and high system scalability via [Docker][docker] images
- Clear project roadmap, extensive development ecosystem and highly skilled developer community
- And many more
## Architecture
TBD
## Quickstart ## Quickstart
@ -60,6 +49,14 @@ This will create `./mainflux_sources` dir, git-clone all the sources from GitHub
It will also give you the instructions how to finish the installation manually. It will also give you the instructions how to finish the installation manually.
## Contributing
Thank you for your interest in Mainflux and wish to contribute!
1. Take a look at our [open issues](https://github.com/mainflux/mainflux/issues).
2. Checkout the [contribution guide](CONTRIBUTING.md) to learn more about our style and conventions.
3. Make your changes compatible to our workflow.
## Community ## Community
- [Google group][forum] - [Google group][forum]