Tutorial: Update license to EPL-v2.0 of your binding in development or pull request

As you may be aware of the license of the addons has been changed to EPL-v2.0. For the source of the bindings already part of openHAB this is already taken care of. But if you are currently developing a binding or have a binding/improvement as an open pull request on the openhab2-addons repository you may need to update the license on your files.

Basically you need to do this if you have added any new source file to a project you need to change the license on your file.

Here I’ll describe the process to update the license. Some steps are only relevant for new bindings. This is explained. The process consists of 3 steps. If you are comfortable with git you can probably skip step 1 and 3.

0. Prerequisites

This tutorial is written using command line versions of the tools used in the project. You can also use graphical user interfaces or even do it from within Eclipse. Use whatever you feel most comfortable with. The tools in this tutorial are:

  1. git
  2. maven

1. Update your source code to the latest source code

As a first step you need to update your source code to be in sync with the latest sources of the openhab2-addons repository. Because you want to have your changes commit after what is already in the repository you need to do a rebase. You need to checkout the branch you want to update and if you use the standard git structure used with openHAB you can use the following command:

git pull --rebase origin master

It might be possible you have merge conflicts during the rebase. This happens most likely with new bindings. This is because all bindings that were part of Eclipse Smart Home are integrated into the openhab2-addons repository. And with that some central files are affected. This can be the pom.xml or feature.xml. To fix this you can take the following steps:

  1. Edit the conflicting files and fix the conflicts. It’s very likely the conflicting lines are for newly added bindings next to your binding. If you are unsure about the original content you can always go the github repository and look up the file.
  2. When you have corrected the files you need to add them with: git add <fixed file>.
  3. If you have done this for all files you can continue the rebase. Git already printed out on the command line the commands needed to continue the rebase: git rebase --continue If you are unsure you can always use the abort option. This will bring you back to the original state before the rebase.

2. Update your source code

This step describes the changes you need to make in your source code.

  1. Update the license header. Run this command from the root of the openhab2-addons source tree:
    mvn -pl :<binding artifactId> license:format
    (Don’t forget the colon : before your binding artifactId!)

If this is a new binding you also need to update the license file:

  1. In the build.properties file replace about.html with NOTICE
  2. Remove the about.html in your binding project.
  3. copy the <openhab2-addons root>/src/etc/NOTICE file to your binding directory (were the about.html was placed).

If you have any libraries included in your project you need to also make a reference about the licenses of those libraries. If you did it correctly you had those in your about.html. With the license update we’ve structured the format this should be written. The third party license information must be added add the end of you NOTICE file and should have the following syntax:

== Third-party Content

[name]
* License: [type of license] License
* Project: [url to project page]
* Source:  [url to source code]

...repeat the block above for all libraries you have included

  • [name] should a simple identifier, like the name of the jar without version or name used by creator of library
  • [type of license] should be a short reference to the license. If you are unsure search the NOTICE files in the openhab2-addons repository for how it’s done for other licenses.

An example:

google-oauth-java-client
* License: Apache 2.0 License
* Project: https://developers.google.com/api-client-library/java/google-oauth-java-client
* Source:  https://github.com/googleapis/google-oauth-java-client

(As a side note, check if you really need those libraries or if functionality is already available in the core framework).

3. Push your changes

When you’ve made your changes. You can check them by building your binding from your binding directory with:
mvn clean install.

The build should complete successfully.
Note: You might get a java.io.FileNotFoundException during the checkstyle run. This is due to the overhaul of the license and something that will be fixed

And finally you need to push your changes back to Github (to update your pull request). First you need to commit your changes. (I hope I don’t have to explain that :slight_smile:) Don’t forget to add the sign off with your name and e-mail.

Because you have rewritten the history with of your branch with the rebase you need to push force the code to the branch. You can push the changes with:

git push --force-with-lease

And now your done. If you have a pull request you can go to Github and should see the pr to be rebuild. This should finish with no errors.

6 Likes

Thanks. This is very well written. You saved me quite a bit of time trying to get this sorted out myself.

One thing I noticed while doing this… If your PR was for a new binding, and if your PR included your new binding in features/openhab-addons/src/main/feature/feature.xml, you may need to manually resolve any possible merge conflicts.

Otherwise, the tutorial worked perfectly for me.

Thanks for mention it. It’s due the ESH bindings that have been merged into the openhab2-addons repository. I also had encountered it, but forgot about it. So I’ve updated the tutorial and added a section about how to fix the rebase conflicts.

1 Like

One other thing to note is that the formatter only works with Java 8 - if you’ve got a newer version of Java you’ll need to make sure you set Java 8 as the in use version before running these commands or you’ll get an error about a required class missing in org.openhab.tools.sat