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.
Your code should conform to pep 8. (I’m ignoring “E501 line too long”.)
- 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:
- Install pep8:
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