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
You should only use Python =< 3.4 methods. If not make it clear in the documentation what kind of Python version you need.
copy the sample plugin directory:
cp -r dev/sample_plugin plugins/myplugin
edit the main file:
Have a look at the following tools to test your code:
apt-get install pep8
Test your code:
pep8 -qq --statistics yourcode.py
pip3 install autopep8
autopep8 yourcode.py -i
pip3 install flake8
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.
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
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 email@example.com