How to contribute code to the MySensors project

[hek]

1. Create a github account
   https://github.com/join

2. It you'd like to contribute to the core MySensors library you have to sign the Contributor License Agreement (CLA) found here:
   https://www.clahub.com/agreements/mysensors/MySensors
   Note 1: This does not apply if you just want to add an examples or 3:rd party libraries.
   Note 2: The CLA-hub service is somewhat broken. If you get an error when trying to sign, just make a note in the pull request "I agree to CLA".

3. Fork the repository.
   Note: All pull-requests must be made against the development branch.
   Go to: https://github.com/mysensors/MySensors/tree/development
   And press the fork button
   

4. Install git on your computer.
   http://git-scm.com/book/en/Getting-Started-Installing-Git

5. Check out your own fork of the MySensors/MySensors project. Open a shell and type:
   > git clone https://github.com/USERNAME/MySensors - Change USERNAME to your own
   You can now make your changes to the source that you have cloned from github. When you are ready and have verified that everything works as expected check in the changes to github by typing.
   > git add -A - Add all changed files to the changeset
   > git commit -m "message explaining what you have done" - Commit changes (locally)
   > git push - Push changes to github

6. Time to create a pull request (PR). Pull requests is used to inform MySensors about your proposed changes or additions to the project. Create it by navigating to your clone on the github web.
   https://github.com/USERNAME/MySensors - Change USERNAME in the url
   Press the "Pull request" button:
   
   Now write a good description and title of your pull request and send it in.
   

And your done!

Most of this guide only needs to be done the first time you send a PR.

[Zeph]

Good guide, thank you.

Can you send a pull request only to the direct parent from which you forked?

[hek]

@Zeph

The project must have a common ancestor. But not necessarily a direct fork.

[Zeph]

I wasn't seeing a step where you selected which relative to send the pull request to.

[hek]

@Zeph

You can press the "Edit" button (top right) on the last picture.

[epierre]

Hello,

I make my contribution as License: Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0), I hope this will not conflict with your CLA...

[Rasmus Eneman]

@epierre MySensors is GPL so all code needs to conform with that, which CC doesn't. Also CC isn't for code.

[hek]

@epierre

https://wiki.creativecommons.org/FAQ#Can_I_use_a_Creative_Commons_license_for_software.3F

[epierre]

@Rasmus-Eneman good, I did not find that mention on the website, and the CLA made me wondering on this...

@hek right I distribute too much under various licenses...but not the same media

[epierre]

@hek you have a CC in an example too : https://github.com/mysensors/Arduino/blob/master/libraries/MySensors/examples/SecretKnockSensor/SecretKnockSensor.ino

[hek]

@epierre

Yeah. I know. Most of that example was copied from Adafruit (see link in example) with the CC license. I'm not a legal expert and unsure if I can "change" the CC. Would prefer having GPL on everything.

[oshwit]

Ok, 2 questions:

1. What's the matter with this Contributor License Agreement? Why is it needed at all? Then in plain words, what the heck do you want from people with it? Because my plain words are: section 2.1a explicitly says that copyright for the contributed code remains with the contributor - and it's usually the copyright assignment is why CLA are put forth at all. Yet section 2.1b says that contributor gives you a license and right to sublicense the code - without naming the license concretely. That sounds as if you ask to give you right to put the code under any license, besides the one under which it is released by contributor. But that's madness. If someone releases code under GPL, and you accept it, you're bound by that GPL.

2. What's the matter with including non Open Source code into the project? Because is CC-NC (non-commercial) is not an Open Source license, because no Open Source license puts limitation on the use of the software (like "only for non-commercial use"). If you include non Open Source code in your project, then your entire project is not Open Source.

So, would be nice to get answers to these licensing questions. Thanks.

[jka]

@oshwit

1. Let me first explain how it works in our case. All code written for mysensors.org should be GPL v2 or higher. If you contribute code to mysensors.org you have to agree on our CLA. If you don't agree with the CLA you should not create a pull request. According to our CLA you still own the copyright to all code you submit (you may for example submit your code to another site under whatever license you like) but you also give mysensors.org the right to release the code under any other license.

It is not uncommon that organisations impose you to sign CLA:s. Even if you contribute code to FSF (Free Software foundation) you need to sign a CLA. One of the reasons is that the organisation in the future more easily can adapt to changes. Another example is the Linux Kernal that is released under GNU GPL v2, in order to change to GNU GPL v3 they whould need a written statement for all contibuting developers, since they didn't sign any CLA:s.

1. We will use GNU GPL v2 or higher as license for all code written for mysensors.org in the repos.

[ntruchsess]

so when you intent to use GNU GPL v2 or higher for all code why would you need the right to change to 'any other license' (even to licenses not compliant with GPL v2 of higher)?

I'd like to contribute but will not sign a CLA that allows this 'change to any other license'.

Feel free to pull any changes that I commit to my fork (as you have done with my UIPEthernet-lib):

https://github.com/ntruchsess/MySensors/tree/ethernet_gw
https://github.com/ntruchsess/MySensors/tree/mqttclient

all changes there are (and will remain) licensed GPL v2 or higher.

[myname]

Copyright
This software is copyright 2012-1014 Sensnology AB. All rights reserved. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial.

[Heinz]

2012-1014? I just can't belive it!

[hek]

@Heinz said:

2012-1014

Yep, typo, should be 2013-2015.

This is where the project started: http://forum.micasaverde.com/index.php/topic,16170.0.html

[DrJeff]

@hek said:

This is where the project started: http://forum.micasaverde.com/index.php/topic,16170.0.html

WOW your vision stayed the same! Cool

[barduino]

Hi @hek

When trying to sign the license agreement I get a very generic We're sorry, but something went wrong. on https://www.clahub.com/agreements/mysensors/Arduino/signatures

Cheers

[hek]

Yes, CLAhub has been messed up a couple of months.

You can just write "I agree to CLA" in the pull request comment until this has been fixed.

[TD22057]

Can anyone explain what the clahub github permissions actually mean? I was going to sign the agreement (which I have no problem with), but it sounds like the app permissions give someone (clahub? mysensors?) access to several things in my github account: all the organizations I belong to, all of my commit texts, etc. My initial reaction is to think that's seems a bit crazy - why does anything need permissions to anything in order for me to accept my agreement to a license? I'm not trying to argue about the need for a CLA - I get that - just wondering what I'm really agreeing to with the clahub application.

[hek]

From what I can tell the most sensitive information needed by CLAHUB (we're running their hosted variant) is your email address (which isn't revealed to the public):
https://github.com/clahub/clahub/blob/040629c91a25043605a0a1c4b100d0bde9c4d74f/config/initializers/omniauth.rb#L22-Lundefined

Anyhow, seems like the developer is looking for a new maintainer of the project:
https://github.com/clahub/clahub/issues/111

The best alternative I've found so far is https://github.com/cla-assistant/cla-assistant (Demo: https://cla-assistant.io/). Like clahub you can self-host it which is nice. Might spin it up to test one of these days...

Meanwhile you can just write "I agree to CLA" in the pull request comment.

To be clear, It is only contributions to the core MySensors library we're talking about here. Upgrading or adding external libraries and new examples is ok without it.

[TD22057]

OK - thanks for the info. The permissions it actually asks me for are:

• user data (email read only)
• repository webhooks and services (admin access)
• organization webhooks (admin access)
• commit statuses (read/write access)
• organization and teams (read only)

Then it shows my other organizations. So it sounds like it can access those (not sure why it would need to), and read any of my commit status messages. I don't know what the webhooks are for but the admin access level made me a bit hesitant. The popup on an org that I belong to says that it can be accessed using the permissions above (which would include admin webhook access which sounds bad). Perhaps it's supposed to mean that it can only access those things for the mysensors repository which makes more sense but the description doesn't say that which is why I was curious about it.

[hek]

@TD22057 said:

Perhaps it's supposed to mean that it can only access those things for the mysensors repository

I surely hope so. I haven't digged through the CLAHub code enough to give a good answer on your (valid) concerns. So I suggest you skip the CLAHub signing for now until we have a less invasive solution up and running.

[hek]

We have now made the development-branch default on github. The master branch will only be used for releases.

This means that all PRs (pull requests) from now on should be forked from and directed to the development-branch.

@Anticimex has done a tremendous work setting up a new build server (Jenkins) that automatically will build all incoming PRs against a few different hardwares. This will help us to keep up the code quality and generate documentation automatically (soon).

Note: Your PR will fail if it generates warnings, so make sure to enable warnings in the Arduino IDE (settings) and fix them before submitting the PR to spare you some time.

Happy hacking
The MySensors team

[GertSanders]

@hek
Hi Henrik, I sent a mail directly earlier today, you can ignore that one. I just read through this thread on how to add examples/code to the DEV branch.
But I still have a question. How do you keep a forked branch in sync with the main development branch?
I have now a clone of the developemnt branch on my Dropbox (I have GIT on my Mac). In the Arduino IDE I point to this Dopbox so that I always have the lastest changes in the Development branch locally after I sync in Github. This allows me to compile my sketches always against a copy of the latest version of the libs and code in the development branch.
But If I fork the DEV to my own branch, how do I keep alle "base" files in sync with the development branch. That is not clear to me from the documentation above.

[hek]

https://help.github.com/articles/syncing-a-fork/

[barduino]

@GertSanders

On GIT for MAC you can also do this

Cheers

[Anticimex]

https://help.github.com/articles/syncing-a-fork/

[cnerone]

Hi all,
I wrote new release of DHT humidity sensor sketch and posted it in github 1 year ago.
It's running on my home for more than a year, its code pubblication is still pending.
Can anyone help me to get it published?

https://github.com/mysensors/MySensorsArduinoExamples/pull/35