Plugin development guidelines

GIT / github

For an git introduction to git see: http://gitimmersion.com/

It you want to publish your plugin, get an github account as soon as possible.

If you don’t get along with the commandline version of the git software, SourceTree by Atlassian is a good client software available free of charge.

Repositories and Branches

SmartHomeNG is located in two repositories:

smarthomeNG/smarthome contains the core of SmartHomeNG
smarthomeNG/plugins contains the plugins of SmartHomeNG

Each repositry consist of two main branches:

master: it contains the stable/release code
develop: is the branch where new features and plugins are merged into

The branch setup is based on this model.

A detailed description (in german language) about the way the workflow is used for SmartHomeNG can be found in the here in the wiki

Getting the Source

you could fork the repository on github or
get the repository: git clone --recursive https://github.com/smarthomeNG/smarthome.git (The –recursive option ensures, that a version of the plugins are checked out as well)
create your own (local) branch (from develop) git checkout -b myplugin develop

Coding style

Your code should conform to pep 8. (I’m ignoring „E501 line too long“.)

Start Coding

copy the sample plugin directory: cp -r dev/sample_plugin plugins/myplugin
edit the main file: vi plugins/myplugin/__init__.py

Tools

Have a look at the following tools to test your code:

pep8

Install pep8: apt-get install pep8
Test your code: pep8 -qq --statistics yourcode.py

autopep8

pip3 install autopep8
autopep8 yourcode.py -i

flake8

pip3 install flake8
flake8 yourcode.py

It can be used as a vim plugin. It checks the code every time I save the file. Most usefull!

Test and Document

Please test and document your code!

In your plugin directory should be a README.md (from the sample_plugin directory). Please fill it with the neccesary information. vi plugins/myplugin/README.md

Basic Rules

only push to the develop branch
changes to contents of the smarthomeNG/smarthome repository must be checked with the SmartHomeNG developer team.
changes to plugins from other developers must be checked with the developer.

Fork (description is deprecated, has to be updated)

Goto SmartHome Repo logged in with your username/password.
Click on ‚fork‘ in the right upper corner.
Change to your Terminal and enter git clone https://USER:PASSWORD@github.com/USER/smarthome
Checkout the develop branch git checkout develop
Change/create a file.
Add the file git add FILE
Commit the changes with a usefull comment: ‚git commit‘
Push your changes to your repository: git pull && git push
Create a pull request on github: base: smarthomeNG/develop compare: USER/develop

Merge (description is deprecated, has to be updated)

If you think your code is ready for prime time send me a pull request via github

Acitve commiters could merge the myplugin branch into develop with:

change the active branch to develop: git checkout develop
merge your plugin into it: git merge --no-ff myplugin
(delete your branch: git branch -d myplugin)
push to github: git push origin develop

.git/config (description is deprecated, has to be updated)

If you have problems pushing, you could check the repo git config. Mine looks like this:

[remote "origin"]
    url = https://github.com/smarthomeNG/smarthome
    fetch = +refs/heads/*:refs/remotes/origin/*

[branch "master"]
    remote = origin
    merge = refs/heads/master

[branch "develop"]
    remote = origin
    merge = refs/heads/develop

Working with the git commandline client

Here are a few tips, if you are working with the commandline client of git:

Useful git commands

list changes since the release with the tag VERSIONTAG: git log --pretty=format:"%s" <VERSIONTAG>..HEAD
undo commit with the id XXXIDXXX: git reset --hard XXXIDXXX && git push origin develop --force
copy commit to current branch: git cherry-pick <commit>

Follow the commit Atom Feed

Global settings

only push the current branch (not all): git config --global push.default current
adapt your user settings:
- git config --global user.name "Your Name"
- git config --global user.email you@example.com