docs: enhance README, add contribution guidelines

unfoldedcircle · Oct 30, 2023 · 104c872 · 104c872
1 parent 655bc4d
commit 104c872
Show file tree

Hide file tree

Showing 4 changed files with 185 additions and 44 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,72 @@
+# Contributing
+
+First off, thanks for taking the time to contribute!
+
+Found a bug, typo, missing feature or a description that doesn't make sense or needs clarification?
+Great, please let us know!
+
+### Bug Reports :bug:
+
+If you find a bug, please search for it first in the [Issues](https://github.com/unfoldedcircle/integration-python-library/issues),
+and if it isn't already tracked, [create a new issue](https://github.com/unfoldedcircle/integration-python-library/issues/new).
+
+### New Features :bulb:
+
+If you'd like to see or add new functionality to the library, describe the problem you want to solve in a
+[new Issue](https://github.com/unfoldedcircle/integration-python-library/issues/new).
+
+### Pull Requests
+
+**Any pull request needs to be reviewed and approved by the Unfolded Circle development team.**
+
+We love contributions from everyone.
+
+⚠️ If you plan to make substantial changes, we kindly ask you, that you please reach out to us first.  
+Either by opening a feature request describing your proposed changes before submitting code, or by contacting us on
+one of the other [feedback channels](#feedback-speech_balloon).
+
+Since this library is being used in integration drivers running on the embedded Remote Two device,
+we have to make sure it remains compatible with the embedded runtime environment and runs smoothly.
+
+Submitting pull requests for typos, formatting issues etc. are happily accepted and usually approved relatively quick.  
+
+With that out of the way, here's the process of creating a pull request and making sure it passes the automated tests:
+
+### Contributing Code :bulb:
+
+1. Fork the repo.
+
+2. Make your changes or enhancements (preferably on a feature-branch).
+
+   Contributed code must be licensed under the [Mozilla Public License 2.0](https://choosealicense.com/licenses/mpl-2.0/),
+   or a compatible license, if existing parts of other projects are reused (e.g. MIT licensed code).  
+   It is required to add a boilerplate copyright notice to the top of each file:
+
+    ```
+    """
+    {fileheader}
+   
+    :copyright: (c) {year} {person OR org} <{email}>
+    :license: MPL-2.0, see LICENSE for more details.
+    """
+    ```
+
+3. Make sure your changes follow the project's code style and the lints pass described in [Code Style](docs/code_guidelines.md).
+
+4. Push to your fork.
+
+5. Submit a pull request.
+
+At this point we will review the PR and give constructive feedback.  
+This is a time for discussion and improvements, and making the necessary changes will be required before we can
+merge the contribution.
+
+### Feedback :speech_balloon:
+
+There are a few different ways to provide feedback:
+
+- [Create a new issue](https://github.com/unfoldedcircle/integration-python-library/issues/new)
+- [Reach out to us on Twitter](https://twitter.com/unfoldedcircle)
+- [Visit our community forum](http://unfolded.community/)
+- [Chat with us in our Discord channel](http://unfolded.chat/)
+- [Send us a message on our website](https://unfoldedcircle.com/contact)
diff --git a/README.md b/README.md
@@ -1,62 +1,57 @@
 # Python API wrapper for the UC Integration API
 
-This is a Python library that can be used for Python based integrations. It wraps the UC Integration API.
+This library simplifies writing Python based integrations for the [Unfolded Circle Remote Two](https://www.unfoldedcircle.com/)
+by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
 
-It's a pre-alpha release. Missing features will be added continuously. Based on the NodeJS implementation.
+It's a pre-alpha release (in our eyes). Missing features will be added continuously.
+Based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
 
-Not supported:
+❗️**Attention:**
+> This is our first Python project, and we don't see ourselves as Python professionals.  
+> Therefore, the library is most likely not yet that Pythonic!  
+> We are still learning and value your feedback on how to improve it :-)
 
-- secure WebSocket
+Not yet supported:
 
-Requires Python 3.10 or newer
+- Secure WebSocket
+- Token based authentication
 
----
+Requirements:
+- Python 3.10 or newer
 
-### Local testing:
-```shell
-python3 setup.py bdist_wheel
-pip3 install --force-reinstall dist/ucapi-$VERSION-py3-none-any.whl
-```
+## Usage
 
-## Code Style
+See [examples directory](examples) for a minimal integration driver example.
 
-- Code line length: 120
-- Use double quotes as default (don't mix and match for simple quoting, checked with pylint).
+More examples will be published.
 
-Install tooling:
-```shell
-pip3 install -r test-requirements.txt
-```
+### Environment Variables
 
-### Verify
+Certain features can be configured by environment variables:
 
-The following tests are run as GitHub action for each push on the main branch and for pull requests.
-They can also be run anytime on a local developer machine:
-```shell
-python -m pylint ucapi
-python -m flake8 ucapi --count --show-source --statistics
-python -m isort ucapi/. --check --verbose 
-python -m black ucapi --check --verbose --line-length 120
-```
+| Variable                           | Values           | Description                                                                                                          |
+|------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------|
+| UC_CONFIG_HOME                     | _directory path_ | Configuration directory to save the user configuration from the driver setup.<br>Default: $HOME or current directory |
+| UC_INTEGRATION_INTERFACE           | _address_        | Listening interface for WebSocket server.<br>Default: `0.0.0.0`                                                      |
+| UC_INTEGRATION_HTTP_PORT           | _number_         | WebSocket listening port.<br>Default: `port` field in driver metadata json file, if not specified: `9090`            |
+| UC_INTEGRATION_MDNS_LOCAL_HOSTNAME | _hostname_       | Published local hostname in mDNS service announcement.<br>Default: _short hostname_ with `.local` domain.            |
+| UC_DISABLE_MDNS_PUBLISH            | `true` / `false` | Disables mDNS service advertisement.<br>Default: `false`                                                             |
 
-Linting integration in PyCharm/IntelliJ IDEA:
-1. Install plugin [Pylint](https://plugins.jetbrains.com/plugin/11084-pylint)
-2. Open Pylint window and run a scan: `Check Module` or `Check Current File`
+## Versioning
 
-### Format Code
-```shell
-python -m black ucapi --line-length 120
-```
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the
+[tags and releases on this repository](https://github.com/unfoldedcircle/integration-python-library/releases).
 
-PyCharm/IntelliJ IDEA integration:
-1. Go to `Preferences or Settings -> Tools -> Black`
-2. Configure:
-- Python interpreter
-- Use Black formatter: `On code reformat` & optionally `On save`
-- Arguments: `--line-length 120`
+## Changelog
 
-### Sort Imports
+The major changes found in each new release are listed in the [changelog](CHANGELOG.md) and
+under the GitHub [releases](https://github.com/unfoldedcircle/integration-python-library/releases).
 
-```shell
-python -m isort ucapi/.
-```
+## Contributions
+
+Please read our [contribution guidelines](./CONTRIBUTING.md) before opening a pull request.
+
+## License
+
+This project is licensed under the [**Mozilla Public License 2.0**](https://choosealicense.com/licenses/mpl-2.0/).
+See the [LICENSE](LICENSE) file for details.
diff --git a/docs/code_guidelines.md b/docs/code_guidelines.md
@@ -0,0 +1,63 @@
+# Code Style
+
+This project uses the [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/) as coding convention, with the
+following customization:
+
+- Code line length: 120
+- Use double quotes as default (don't mix and match for simple quoting, checked with pylint).
+
+## Tooling
+
+Install all code linting tools:
+
+```shell
+pip3 install -r test-requirements.txt
+```
+
+### Linting
+
+```shell
+python -m pylint ucapi
+```
+
+- The tool is configured in `.pylintrc`.
+
+Linting integration in PyCharm/IntelliJ IDEA:
+1. Install plugin [Pylint](https://plugins.jetbrains.com/plugin/11084-pylint)
+2. Open Pylint window and run a scan: `Check Module` or `Check Current File`
+
+### Sort Imports
+
+Import statements must be sorted with [isort](https://pycqa.github.io/isort/):
+
+```shell
+python -m isort ucapi/.
+```
+
+- The tool is configured in `pyproject.toml` to use the `black` code-formatting profile.
+
+### Format Code
+
+Source code is formatted with the [Black code formatting tool](https://github.com/psf/black):
+
+```shell
+python -m black ucapi --line-length 120
+```
+
+PyCharm/IntelliJ IDEA integration:
+1. Go to `Preferences or Settings -> Tools -> Black`
+2. Configure:
+- Python interpreter
+- Use Black formatter: `On code reformat` & optionally `On save`
+- Arguments: `--line-length 120`
+
+## Verify
+
+The following tests are run as GitHub action for each push on the main branch and for pull requests.
+They can also be run anytime on a local developer machine:
+```shell
+python -m pylint ucapi
+python -m flake8 ucapi --count --show-source --statistics
+python -m isort ucapi/. --check --verbose 
+python -m black ucapi --check --verbose --line-length 120
+```
diff --git a/docs/setup.md b/docs/setup.md
@@ -0,0 +1,11 @@
+# Development Setup
+
+This library requires Python 3.10 or newer.
+
+## Local installation
+
+```shell
+python3 setup.py bdist_wheel
+pip3 install --force-reinstall dist/ucapi-$VERSION-py3-none-any.whl
+```
+