99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# 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
|
|
```shell
|
|
$ 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
|
|
```shell
|
|
$ 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:
|
|
```shell
|
|
$ git add .
|
|
$ git commit -m "Put your commit text here. Please be concise, but descriptive."
|
|
$ git push origin HEAD
|
|
```
|
|
|
|
6. Submit your pull request on GitHub
|
|
|
|
- On GitHub, navigate to the [blinkpy](https://github.com/fronzbot/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. To see what's wrong, you can find your pull request [here](https://travis- ci.org/fronzbot/blinkpy/pull_requests) and click on the failing test to see the logs. Those logs will indicate, as best as they can, what is causing that test to fail.
|
|
|
|
|
|
## 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``
|
|
|
|
```shell
|
|
$ pip3 install tox
|
|
```
|
|
|
|
You can then run all of the tests with the following command:
|
|
|
|
```shell
|
|
$ tox
|
|
```
|
|
|
|
### Tips
|
|
|
|
If you only want to see if you can pass the local tests, you can run `tox -e py35` (or whatever python version you have installed. Only `py35`, `py36`, and `py37` 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 py35 -- 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):
|
|
|
|
```shell
|
|
$ 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 filw 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.
|