Binding development // github How-To // Help needed

Hi guys,

I was wondering if there are other folks out there who are at war with git. :cry:
Everytime I want to do sometting I ended up googling the right commands. Often the results I’m using are not successful and they have to be adapted to my current setup with OH.
So I would like to start a How-To specifically to the OH binding development. IMHO for a contributor there are only a few use cases that need to be documented:

  1. create your own branch (fork the current openhab/openhab project) (via github.com web)
  2. clone it on your local machine (“git clone ‘your repository’”)
  3. do some development cycles (“git commit” and “git push” to your repository fork, right?)
  4. update your fork with new developments from the main branch (what’s the git command there?) then do 3.
  5. create a pull request with your binding (via github.com web) => do more bugfixing (like 3.)
  6. wait for feedback from maintainers
  7. incorporate feedback into your branch (‘git commit’ and ‘git push’, right?). Do that several times til finished
  8. wait for the final feedback that your binding will be accepted “As-is”. So you have to squash all commits into one (which git commands?, ‘git rebase -i origin/master’) and then?
  9. perhaps update fork with new developments from main branch (more ‘git commit’ and ‘git push’?) and then again squash all commits into one?

So “Masters of git”, can you please help? Change where changes are needed, insert where necessary and correct where things are wrong.

With the final result I will create a wiki entry.

Thanks and have a nice weekend,
Michael

I use SourceTree which is free and very good at helping out with the git stuff.

Thanks Ben, I tried that, too. But if you don’t know which buttons to press or which actions to take a graphical user interface doesn’t really help. :smile:
Even the git process in general is documented very well on the web. But I still fail to mirror that to the OH project especially as we have no write access to certain areas of the project (Which is a good thing ;-))

step 4 is git pull or git merge upstream/master (https://help.github.com/articles/syncing-a-fork/)

One thing that is often missing from guides like this is a discussion of the project’s culture and process. Everything listed above has a technical focus but I wonder how well received a new pull request is received when it appears out of the blue without an issue attached to it. Some discussion of how to broach the subject with @kai, @teichsta, et al to make sure the change is in keeping with the design and roadmap, and it is something that would be well received would be, IMHO as useful if not more useful than just the technical info.

Note that openHAB 1 binding development will very soon be outdated and not suggested anymore and that a lot (what repo to check out, how to setup the IDE, etc.) will change heavily.

For openHAB 2, I have created a few documents so far, which should address some of the culture and process topics @rlkoshak mentions:


https://github.com/openhab/openhab2/blob/master/docs/sources/development/ide.md
https://github.com/openhab/openhab2/blob/master/docs/sources/development/bindings.md

None of these describe the specifics of how to handle git, though. But as we are following the standard open source processes, I also think that linking to some good pages on Github help should be sufficient - after all, this is nothing openHAB specific, but things to know when doing open source work.

1 Like