OrgGo/Mainflux.mainflux
1
0
Fork 0
mirror of https://github.com/mainflux/mainflux.git synced 2025-04-24 13:48:49 +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
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.
These are just guidelines, not rules, use your best judgment and feel free to
propose changes to this document in a pull request.
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.
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)
* [Pull Requests](#pull-requests)
* [Merge Approval](#merge-approval)
* [Documentation Styleguide](#documentation-styleguide)
Reporting issues is a great way to contribute to the project. We always appreciate a well-written,
thorough bug reports.
## 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:
- 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](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.
- What were you trying to achieve?
- What are the expected results?
- What are the received results?
- What are the steps to reproduce the issue?
- In what environment did you encounter the issue?
## Pull requests
Good pull requests - patches, improvements, new features - are a fantastic
help. They should remain focused in scope and avoid containing unrelated
commits.
Good pull requests (e.g. 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 ask first** before embarking any significant pull request (e.g. implementing new features,
refactoring code etc.), otherwise you risk spending a lot of time working on something that the
maintainers 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).
Please adhere to the coding conventions used throughout the project. If in doubt, consult the
following style guides:
* Follow the [EffectiveGo](https://golang.org/doc/effective_go.html) styleguide
* Follow the [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
- [Effective Go](https://golang.org/doc/effective_go.html)
- [Google's JavaScript styleguide](https://google.github.io/styleguide/jsguide.html)
Adhering to the following process is the best way to get your work
included in the project:
Adhering to the following process is the best way to get your work included in the project:
1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your
fork, and configure the remotes:
1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork, and configure
the remotes:
```bash
# Clone your fork of the repo into the current directory
@ -65,7 +54,7 @@ included in the project:
cd mainflux
# 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:
@ -75,71 +64,29 @@ included in the project:
git pull upstream master
```
3. 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](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:
3. Create a new topic branch from `master` using the naming convention `mainflux-[issue-num]` to
help us keep track of your contribution scope:
```bash
git checkout -b mainflux-[issue-num]
```
4. Commit your changes in logical chunks. Please adhere to these [git commit
message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
or your code is unlikely be merged into the main project. Use Git's
[interactive rebase](https://help.github.com/articles/about-git-rebase/)
feature to tidy up your commits before making them public.
4. Commit your changes in logical chunks. When you are ready to commit, make sure to write a Good
Commit Message™. Consult the [https://github.com/erlang/otp/wiki/Writing-good-commit-messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
if you're not sure what constitutes a Good Commit Message™. Use [interactive rebase](https://help.github.com/articles/about-git-rebase)
to group your commits into logical units of working 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.
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](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:
```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
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:
@ -147,42 +94,5 @@ included in the project:
git push origin mainflux-[issue-num]
```
7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
with a clear title and 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
7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title
and detailed description.

35
README.md
View File

@ -7,31 +7,20 @@
![banner][banner]
Mainflux is modern, massively-scalable, highly-secured open source and patent-free IoT cloud
platform written in Go.
Mainflux is modern, scalable, secure open source and patent-free IoT cloud platform written in Go.
It allows device, user and application connections over various network protocols, like HTTP, MQTT,
WebSocket, and CoAP, making a seamless bridge between them. It is used as the IoT middleware for
building complex IoT solutions.
It accepts user, device, and application connections over various network protocols (i.e. HTTP,
MQTT, WebSocket, CoAP), thus making a seamless bridge between them. It is used as the IoT middleware
for building complex IoT solutions.
For more details, check out the [official documentation][docs].
## Features
An extensive (and incomplete) list of features includes:
- Responsive and scalable microservice architecture
- Set of clean APIs: HTTP RESTful, MQTT, WebSocket and CoAP
- SDK - set of client libraries for many HW platforms in several programming languages: C/C++, JavaScript, Go and Python
- 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
- Protocol bridging (i.e. HTTP, MQTT, WebSocket, CoAP)
- Device management and provisioning
- Fine-grained access control
- Container-based deployment using [Docker][docker]
## 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.
## 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
- [Google group][forum]