Home Assistant

Setup Development

Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses Python 3 for the backend and Polymer (Web components) for the frontend.

Home Assistant is open-source and MIT licensed. The source can be found here:

Starting development

You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.
Visit the the Home Assistant repository first and click fork in the top right.

We suggest that you setup a virtual environment using venv before running the setup script.

$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
$ cd home-assistant
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
$ script/setup

On Windows you can use python setup.py develop instead of the setup script.

After following these steps, running hass will invoke your local installation.

Testing your work

Testing your work requires tox to be installed:

$ pip3 install tox

Prevent Linter Errors

Home Assistant enforces strict PEP8 style compliance on all code submitted. You can save yourself the hassle of extra commits just to fix style errors by enabling the flake8 git commit hook. It will check your code when you attempt to commit to the repo. It will block the commit if there are any style issues, giving you a chance to fix it.

$ pip install flake8 flake8-docstrings
$ flake8 --install-hook

The flake8-docstrings extension will check docstrings according to PEP257 when running flake8.

Submitting improvements

Improvements to Home Assistant should be submitted one feature at a time using GitHub pull requests.

  1. From your fork, create a new branch to hold your changes
    git checkout -b some-feature
  2. Make the changes you want
  3. Test your changes and check for style violations
    tox
  4. Commit the changes
    git add .
    git commit -m "Added some-feature"
  5. Push your committed changes back to your fork on GitHub
    git push origin HEAD
  6. Follow these steps to create your pull request.

Catching up with Reality

If you’re taking a while developing your feature request and would like to catch up with what’s in the current Home Assistant dev branch, you can use git rebase to do so. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant and then replay all of your commits on top.

# Run this from your feature branch
$ git fetch upstream dev  # to pull the latest changes into a local dev branch
$ git rebase upstream/dev # to put those changes into your feature branch before your changes

If rebase detects conflicts, you can repeat the following process until all changes have been resolved:

  1. git status will show you the file with the conflict.
  2. Edit the file and resolving the lines between <<<< | >>>>
  3. Add the modified file git add <file> or git add .
  4. Continue rebase git rebase --continue
  5. Repeat until you’ve resolved all conflicts.

Further reading