Merge pull request #273 from plugwise/improve

Textual improvements and addition of codeowners

Author: CoMPaTech

.github/workflows/verify.yml

@@ -4,7 +4,7 @@
 name: Latest commit
 
 env:
-  CACHE_VERSION: 3
+  CACHE_VERSION: 4
   DEFAULT_PYTHON: "3.10"
   PRE_COMMIT_HOME: ~/.cache/pre-commit
 
@@ -153,6 +153,10 @@ jobs:
         run: |
           . venv/bin/activate
           pre-commit run --show-diff-on-failure --color=always --all-files --hook-stage manual pylint
+      - name: Lint markdown files
+        run: |
+          . venv/bin/activate
+          pre-commit run --show-diff-on-failure --color=always --all-files --hook-stage manual markdownlint
 
   prepare-test-cache:
     runs-on: ubuntu-latest

.markdownlint.yaml

@@ -0,0 +1,2 @@
+default: true
+MD013: false

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 ci:
-  skip: [pylint]
+  skip: [pylint, markdownlint]
   submodules: true
 
 default_language_version:
@@ -111,3 +111,7 @@ repos:
         language: script
         types: [python]
         files: ^plugwise/.+\.py$
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.33.0
+    hooks:
+      - id: markdownlint

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Plugwise CodeOwners
+# Order is important. The last matching pattern has the most precedence.
+
+# Specific files
+setup.cfg @plugwise/devs
+setup.py @plugwise/devs
+pyproject.toml @plugwise/devs
+requirements*.txt @plugwise/devs
+
+# Main code
+/plugwise/ @plugwise/devs
+/userdata/ @plugwise/devs
+
+# Tests and development support
+/tests/ @bouwew @compatech
+/scripts/ @bouwew @compatech
+
+# NET specific
+/plugwise/smile.py @bouwew @compatech
+
+# USB specific
+/plugwise/connections/ @brefra
+/plugwise/controller.py @bouwew @brefra
+/plugwise/messages/ @brefra
+/plugwise/nodes/ @brefra
+/plugwise/parser.py @brefra
+/plugwise/stick.py @brefra
+/plugwise/util.py @brefra
+

CODEOWNERS

@@ -1,17 +1,19 @@
 # Plugwise python module
 
-This module is the backend for the [`plugwise` component](https://github.com/home-assistant/core/tree/dev/homeassistant/components/plugwise) which we maintain in Home Assistant Core.
+This module is the backend for the [`plugwise` component](https://github.com/home-assistant/core/tree/dev/homeassistant/components/plugwise) which we maintain as co-code owners Home Assistant Core.
 
 Our main usage for this module is supporting [Home Assistant](https://www.home-assistant.io) / [home-assistant](http://github.com/home-assistant/core/)
 
 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/plugwise)
-[![CodeFactor](https://www.codefactor.io/repository/github/plugwise/python-plugwise/badge)](https://www.codefactor.io/repository/github/plugwise/python-plugwise)
-[![Latest release](https://github.com/plugwise/python-plugwise/workflows/Latest%20release/badge.svg)](https://github.com/plugwise/python-plugwise/actions)
-[![codecov](https://codecov.io/gh/plugwise/python-plugwise/branch/main/graph/badge.svg)](https://codecov.io/gh/plugwise/python-plugwise)
 [![PyPI version fury.io](https://badge.fury.io/py/plugwise.svg)](https://pypi.python.org/pypi/plugwise/)
+
+[![Latest release](https://github.com/plugwise/python-plugwise/workflows/Latest%20release/badge.svg)](https://github.com/plugwise/python-plugwise/actions)
 [![Newest commit](https://github.com/plugwise/python-plugwise/workflows/Latest%20commit/badge.svg)](https://github.com/plugwise/python-plugwise/actions)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/plugwise/python-plugwise/main.svg)](https://results.pre-commit.ci/latest/github/plugwise/python-plugwise/main)
 
+[![CodeFactor](https://www.codefactor.io/repository/github/plugwise/python-plugwise/badge)](https://www.codefactor.io/repository/github/plugwise/python-plugwise)
+[![codecov](https://codecov.io/gh/plugwise/python-plugwise/branch/main/graph/badge.svg)](https://codecov.io/gh/plugwise/python-plugwise)
+
 ## Integration
 
 ### Home-Assistant Integration
@@ -20,23 +22,27 @@ Our main usage for this module is supporting [Home Assistant](https://www.home-a
 
 [![Generic badge](https://img.shields.io/badge/HA%20core-yes-green.svg)](https://github.com/home-assistant/core/tree/dev/homeassistant/components/plugwise)
 
-Works out of the box with every Home Assistant installation
+Works out of the box with every Home Assistant installation, use the button below to install
+
+[![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integrations/)
 
 ### Home-Assistant custom_component (beta)
 
-Intended for users helping us test new features (use at your own risk)
+We do (also) maintain a `custom_component`, please note this is **only** intended for users helping us test new features (use at your own risk)
 
 [![Generic badge](https://img.shields.io/github/v/release/plugwise/plugwise-beta)](https://github.com/plugwise/plugwise-beta)
-[![Generic badge](https://img.shields.io/badge/HA%20custom_component-yes-green.svg)](https://github.com/plugwise/plugwise-beta)
+
+You can add our `custom_component` repository to HACS, do note that we do not intent for our `beta` `custom_component` to be included in the HACS repository.
+
 [![Generic badge](https://img.shields.io/badge/HACS-add%20our%20repo-yellow.svg)](https://github.com/plugwise/plugwise-beta)
 
-See the [`plugwise-beta`](https://github.com/plugwise/plugwise-beta) repository for more info. Requires additional configuration/handling to get your integration running.
+See the [`plugwise-beta`](https://github.com/plugwise/plugwise-beta) repository for more info.
 
 ## Development/patches
 
-Like Home Assistant Core we use `pre-commit` to validate your commits and eventually PRs.
+Like Home Assistant Core we use `pre-commit` and additionally run [pre-commit.ci](http://pre-commit.ci) to automatically validate your commits and PRs.
 
-Please make sure you at least ran `scripts/setup.sh` before attempting to `git commit`. But we sincerely recommended to also use local testing, see `tests/README.md` for more information.
+If you want to create a PR please make sure you at least run `scripts/setup.sh`. This will ensure your environment is set up correctly before attempting to `git commit`. We sincerely and highly recommended also setting up local testing, see [`tests/README.md`](https://github.com/plugwise/python-plugwise/blob/main/tests/README.md) for more information and run `scripts/setup_test.sh` to prepare your environment.
 
 ## Project support status
 
@@ -76,8 +82,8 @@ Origins (from newest to oldest):
 - Networked Plugwise Anna module with custom_module - `haanna/anna-ha` via <https://github.com/laetificat> (Kevin)
 - USB-based stick module with custom_module - `plugwise-stick/plugwise` by @brefra (Frank)
 - USB-plugwise module - `plugwise` by <https://github.com/cyberjunky/python-plugwise> (Ron) originally by <https://github.com/aequitas/python-plugwise> (Johan) (with reference only in license to Sven)
-- Sensor for Plugwise Smile P1 integration - `home-assistant-sensor-plugwise-smile-p1` by <https://bitbucket.org/jvdschoot/home-assistant-sensor-plugwise-smile-p1> (Jeroen van der Schoot) 
+- Sensor for Plugwise Smile P1 integration - `home-assistant-sensor-plugwise-smile-p1` by <https://bitbucket.org/jvdschoot/home-assistant-sensor-plugwise-smile-p1> (Jeroen van der Schoot)
 
 ## Thanks
 
-On behalf all of us, big thanks to Plugwise and community members @riemers and @tane from [HAshop](https://hashop.nl)for their support and obviously all our users and testers who dealt with our typos and challenges. Disclaimer, while we are communicating with Plugwise and they expressed their gratitude through their newsletter, we are not part of Plugwise as a company. We are just a bunch of guys anxious to get our (and your) Plugwise products working with Home Assistant.
+On behalf all of us, big thanks to Plugwise and community members @riemers and @tane from [HAshop](https://hashop.nl) for their support and obviously all our users and testers who dealt with our typos and challenges. Disclaimer, while we are communicating with Plugwise and they expressed their gratitude through their newsletter, we are not part of Plugwise as a company. We are just a bunch of guys anxious to get our (and your) Plugwise products working with Home Assistant.

README.md

@@ -4,35 +4,35 @@
 
 Needed:
 
- - [ ] Github account (or organisation and account(s))
- - [ ] Codecov account (just choose 'login with github')
- - [ ] CodeFactor account (again, login with github)
- - [ ] Add codecov as an integration from Github's integrations (basically 'buy' it, except its at no cost)
+- [ ] Github account (or organisation and account(s))
+- [ ] Codecov account (just choose 'login with github')
+- [ ] CodeFactor account (again, login with github)
+- [ ] Add codecov as an integration from Github's integrations (basically 'buy' it, except its at no cost)
 
 ## Configuration
 
 After the initial setup of the repo/initial commit, walk the repo-settings on GitHub using your browser.
 
- - [ ] [Set the product image, turn off wiki and automatically delete branches (from defaults)](https://github.com/plugwise/python-plugwise/settings)
- - [ ] [Activate both dependabots and keep dependency graph open](https://github.com/plugwise/python-plugwise/settings/security_analysis)
- - [ ] [Integrations, configure codecov (should show up from organisation)](https://github.com/plugwise/python-plugwise/settings/installations)
+- [ ] [Set the product image, turn off wiki and automatically delete branches (from defaults)](https://github.com/plugwise/python-plugwise/settings)
+- [ ] [Activate both dependabots and keep dependency graph open](https://github.com/plugwise/python-plugwise/settings/security_analysis)
+- [ ] [Integrations, configure codecov (should show up from organisation)](https://github.com/plugwise/python-plugwise/settings/installations)
 
 For this step you might need to follow [this publishing guide](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/) taking you through most of the steps. Note that the projects on PyPi already [**need to exist**](https://packaging.python.org/tutorials/packaging-projects/) so use a generic token first and later adjust that to only this project (as explained on that howto):
 
- - [ ] [Configure secrets for PYPI_TOKEN and TESTPYPI_TOKEN](https://github.com/plugwise/Plugwise-Smile/settings/secrets)
+- [ ] [Configure secrets for PYPI_TOKEN and TESTPYPI_TOKEN](https://github.com/plugwise/Plugwise-Smile/settings/secrets)
 
 ## Initializing pypi
 
-Once the project is ready for upload to test (i.e. version number ending in `a0` or something likewise): upload it manually using `twine upload`: 
+Once the project is ready for upload to test (i.e. version number ending in `a0` or something likewise): upload it manually using `twine upload`:
 
 Prepare:
 
- - [ ] `python3 -m venv venv ; source venv/bin/activate ; pip install --upgrade pip; pip install -r requirements_test.txt ; pip install --upgrade setuptools wheel twine`
+- [ ] `python3 -m venv venv ; source venv/bin/activate ; pip install --upgrade pip; pip install -r requirements_test.txt ; pip install --upgrade setuptools wheel twine`
 
-Package: (** ensure you are in your venv**)
+Package: (**ensure you are in your venv**)
 
- - [ ] [pypi packaging](https://packaging.python.org/tutorials/packaging-projects/)
- - [ ] `python3 setup.py sdist bdist_wheel`
+- [ ] [pypi packaging](https://packaging.python.org/tutorials/packaging-projects/)
+- [ ] `python3 setup.py sdist bdist_wheel`
 
 Then reconfigure your tokens on the pypi website accordingly (only allowing project updates) and carry on.
 
@@ -65,6 +65,4 @@ From [integrations](https://github.com/plugwise/python-plugwise/settings/install
 
 If you push templates within the `.github/ISSUE_TEMPLATES` directory they should be available, if not:
 
- - [ ] Go to [issue templates](https://github.com/plugwise/python-plugwise/issues/templates/edit) and create them
-
-
+- [ ] Go to [issue templates](https://github.com/plugwise/python-plugwise/issues/templates/edit) and create them

tests/INIT.md

@@ -1,29 +1,35 @@
 # Testing (for developers)
 
-Plugwise-Smile has to be in working and functioning condition on all circumstances. Hence testing.
+Plugwise-Smile has to be in working and functioning condition on all circumstances. Hence testing is applied and tested through [Github Actions](https://github.com/plugwise/python-plugwise/actions).
 
 ## Tests
+
 From the above list of setups a number of values is selected to be asserted. Currently we have the following asserts in place:
 
 Information gathering: (negative)
+
 - Check handling against a Smile that 'times out' during request
 - Check handling against a Smile refusing contact (`internal server error`)
 
 Service handling (i.e. changing setpoint or switching a relay)
+
 - Check against a Smile not accepting change (`internal server error`) (negative)
 - Switch a relay, change a setpoint or change a schema/preset (positive)
 
 Data processing (positive)
+
 - Includes checking various `measures` and settings for each device / location / combination of both
 
 ## Running tests against Plugwise Smile
 
-Our tests are mainly conducted locally by the contributors and using Github Actions. You can always look up the latest (hopefully successful) build at (python-plugwise Github actions)[https://github.com/plugwise/python-plugwise/actions].
+`*) This states Smile as unfortunately tests for USB are still to be added`
+
+Our tests are mainly conducted locally by the contributors and using Github Actions, see the workflows in `.github/workflows`. You can always look up the latest (hopefully successful) build at [python-plugwise Github actions](https://github.com/plugwise/python-plugwise/actions).
 
-If you want to run tests locally, use the provided `scripts/setup.sh` to initialize and enable your virtualenv using `source venv/bin/activate`.
+If you want to run tests locally, use the provided `scripts/setup_test.sh` to initialize and enable your virtualenv using `source venv/bin/activate`.
 
-Without your virtualenv, run the `scripts/setup_test.sh` script. With that (and your virtualenv enabled) you can run `scripts/tests_and_coverage.sh` or `scripts/complexity` to show areas that need Cyclometic Complexity improving.
+Without your virtualenv, run the `scripts/setup_test.sh` script. With that (and your virtualenv enabled) you can run `scripts/tests_and_coverage.sh` or `scripts/complexity.sh` to show areas that need Cyclometic Complexity improving.
 
 ## Quality
 
-Code quality is checked (through Github Actions) at (CodeFactor)[https://www.codefactor.io/repository/github/plugwise/python-plugwise] and (codecov.io)[https://app.codecov.io/gh/plugwise/python-plugwise] as depicted by the badges on the (main repository page)[https://github.com/plugwise/python-plugwise].
+Code quality is checked (through [Github Actions](https://github.com/plugwise/python-plugwise/actions)) at [CodeFactor](https://www.codefactor.io/repository/github/plugwise/python-plugwise) and [codecov.io](https://app.codecov.io/gh/plugwise/python-plugwise) as depicted by the badges on the [main repository page](https://github.com/plugwise/python-plugwise).