openhab-docs icon indicating copy to clipboard operation
openhab-docs copied to clipboard
verified publisher icon openhab

Improve the developer insturctions for new contributors: Setting up the development environment

Open masipila opened this issue 2 years ago • 4 comments

Hi,

Background and context I'm about to start my first add-on contribution to improve the existing aWATTar Binding, see the plan here: https://community.openhab.org/t/awattar-binding-beta-and-discussion/110497/76?u=masipila

What I have done so far

  • I have read https://www.openhab.org/docs/developer/ and installed Maven, JDK 11 and Eclipse
  • I have read https://www.openhab.org/docs/developer/guidelines.html
  • I have read https://www.openhab.org/docs/developer/bindings/
  • I have read the current code of the aWATTar Binding and I have a good idea where to start the development
  • I have read the https://github.com/openhab/openhab-addons/blob/main/README.md and https://github.com/openhab/openhab-addons/blob/main/CONTRIBUTING.md

My confusion and purpose of this issue I'm overwhelmed by the fact that there are dozens and dozens of different repositories, including one for core and one for add-ons.

I know that I need to fork the openhab-addons and work in a feature branch, but I did not find any simple guidelines how I can actually start the development so that I would have a working devevelopment instance of openHab together with the forked codebase of openhab/openhab-addons. I mean instructions like

  • First clone openhab-core and openhab-addons and foo, bar, baz
  • Compile them with these commands and do foo, bar, baz
  • Observe that you are now able to see a running vanilla openHab
  • Then make some change and to see that reflected in your dev instance, do this and that

It's worth mentioning that my previous programming experience on the last 15 years or so is mainly from the PHP world and it's been a good while (read: 20 years) since I last wrote Java. That's the main reason why certain things that are most probably very obvious and go with saying for Java programmers are not obvious to me so I would appreciate some guidance AND propose that we add that guidance to the Developer Guide as well.

I'm familiar with Docker if that's the common practice amon openHab contributors.

Cheers, Markus

masipila avatar Feb 19 '23 17:02 masipila

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/awattar-binding-beta-and-discussion/110497/88

openhab-bot avatar Feb 19 '23 17:02 openhab-bot

Hi, as far as I remember this is what I did to start working on a binding:

  • Fork openhab-addons on github
  • Clone your forked repo (I use Github desktop for that).
  • Go to the directory of the binding you want to modify, e.g. cd bundles/org.openhab.binding.awattar
  • In this directory, run mvn clean package. This will take a while on the first run every day, as it downloads a lot of things. Subsequent runs on the same day are much faster. If you have multiple versions of java on your machine, be sure to set JAVA_HOME correctly, otherwise the build will fail.
  • In subdirectory target, which is now created, you find the jar file with the binding.
  • Download openHAB for your local development machine from https://www.openhab.org/download/ . For development I normally use the snapshot build. Unpack it somewhere on your machine. This is the test environment for your binding.
  • Copy the jar file built with maven to the subdirectory addons of the just unpacked openHAB distribution
  • Start the distribution with the start script (start.sh/start.bat).
  • Configure your binding in the admin UI or with config files, whatever you prefer.
  • Find logfiles in userdata/logs
  • When developing your own code, run mvn spotless:apply before compiling to ensure that the coding styleguide is met.
  • Watch for warnings, they should be elimitated as far as possible before creating a PR.
  • Be sure to sign every commit (flag -s, maybe this can be configured in git somewhere), otherwise the automated PR check will fail and your PR will not be merged.

I'm sure this list is not complete, but maybe it helps as a starting point.

Wolfgang1966 avatar Feb 20 '23 15:02 Wolfgang1966

Good advice from @Wolfgang1966

Using Docker to run openhab for development is a useful trick. You can copy your built target/*.jar to the addons folder to deploy it for testing.

https://www.openhab.org/docs/installation/docker.html

DougCulnane-Ded avatar Feb 22 '23 17:02 DougCulnane-Ded

I have read https://www.openhab.org/docs/developer/ and installed Maven, JDK 11 and Eclipse

Did you install Eclipse yourself or did you follow the instructions?

https://www.openhab.org/docs/developer/ide/eclipse.html

After following these instructions the code is cloned to your computer. It also has instructions on how to import add-on code and test your changes.

wborn avatar Aug 10 '23 20:08 wborn