Skip to content

Latest commit

 

History

History
110 lines (66 loc) · 4.4 KB

CONTRIBUTING.rst

File metadata and controls

110 lines (66 loc) · 4.4 KB
Raw

Contributing to blinkpy

Everyone is welcome to contribute to blinkpy! The process to get started is described below.

Fork the Repository

You can do this right in github: just click the 'fork' button at the top right.

Start Developing

  1. Setup Local Repository

    $ git clone https://github.com/<YOUR_GIT_USERNAME>/blinkpy.git
$ cd blinkpy
$ git remote add upstream https://github.com/fronzbot/blinkpy.git

  2. Create virtualenv and install dependencies

    $ python -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ pip install -r requirements_test.txt
$ pre-commit install

  3. Create a Local Branch

    First, you will want to create a new branch to hold your changes: git checkout -b <your-branch-name>

  4. Make changes

    Now you can make changes to your code. It is worthwhile to test your code as you progress (see the Testing section)

  5. Commit Your Changes

    To commit changes to your branch, simply add the files you want and the commit them to the branch. After that, you can push to your fork on GitHub:

    $ git add .
$ git commit
$ git push origin HEAD

  6. Submit your pull request on GitHub

    • On GitHub, navigate to the blinkpy repository.
    • In the "Branch" menu, choose the branch that contains your commits (from your fork).
    • To the right of the Branch menu, click New pull request.
    • The base branch dropdown menu should read dev. Use the compare branch drop-down menu to choose the branch you made your changes in.
    • Type a title and complete the provided description for your pull request.
    • Click Create pull request.
    • More detailed instructions can be found here: Creating a Pull Request <https://help.github.com/articles/creating-a-pull-request>`__

  7. Prior to merge approval

    Finally, the blinkpy repository uses continuous integration tools to run tests prior to merging. If there are any problems, you will see a red 'X' next to your pull request.

Testing

It is important to test the code to make sure your changes don't break anything major and that they pass PEP8 style conventions. First, you need to locally install tox

$ pip install tox

You can then run all of the tests with the following command:

$ tox

Tips

If you only want to see if you can pass the local tests, you can run tox -e py39 (or whatever python version you have installed. Only py39 through py312 will be accepted). If you just want to check for style violations, you can run tox -e lint. Regardless, when you submit a pull request, your code MUST pass both the unit tests, and the linters.

If you need to change anything in requirements.txt for any reason, you'll want to regenerate the virtual envrionments used by tox by running with the -r flag: tox -r

If you want to run a single test (perhaps you only changed a small thing in one file) you can run tox -e py37 -- tests/<testname>.py -x. This will run the test <testname>.py and stop testing upon the first failure, making it easier to figure out why a particular test might be failing. The test structure mimics the library structure, so if you changed something in sync_module.py, the associated test file would be in test_sync_module.py (ie. the filename is prepended with test_.

Catching Up With Reality

If your code is taking a while to develop, you may be behind the dev branch, in which case you need to catch up before creating your pull-request. To do this you can run git rebase as follows (running this on your local branch):

$ git fetch upstream dev
$ git rebase upstream/dev

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

  1. git status shows you the file with a conflict. You will need to edit that file and resolve the lines between <<<< | >>>>.
  2. Add the modified file: git add <file> or git add ..
  3. Continue rebase: git rebase --continue.
  4. Repeat until all conflicts resolved.