First off, thanks for taking the time to contribute!
All types of contributions are encouraged and valued.
And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
- Star the project
- Tweet about it or share in social media
- Create examples & refer this project in your project's readme. I can add your example in my example repository if its really helpful, including use cases in more sophisticated integrations
- Mention the project at local meetups/conferences and tell your friends/colleagues
- Donate to cover the costs of maintaining it
When contributing to this project, you must agree that you have authored 100% of the content or that you have the necessary rights to the content, and agree to release it under the license of the project.
If you want to tackle any issues, un-existing features, please do have a look at good-first-issues. Issues are separated by perceived level of difficulty (beginner, intermediate) and type of contribution (bug, feature, documentation etc.). If you wish to propose a feature or bugfix, they are totally welcome and we could discuss it on discord/email (links in README) before you start working on it.
Good first issues are meant for humans to practice coding, trying to understand the codebase, propose improvements or flaws while reviewing the codebase etc. Please refrain from automating PRs with low quality fixes. I can do most good first issues on my own without anybody's help, so introduce more machines here is not the point.
Partial contributions are also taken if its easier to continue working on it. In this case, you can submit your fork to merge into a separate branch, where someone else can develop it until it meets the required standards for release.
To start developing and complete the contribution, following steps may be followed:
- Fork the repository and clone it to your local machine.
- Setup python environment, preferably using
uv, instructions are in the docs. - There are some test things under
tests/helper-scriptsdirectory or in the examples repository, especially the simulators (they may not be up to date, one could take what one needs). These can be used to test your changes. - All code must follow PEP 8 style guide. One needs to use ruff to check for style issues -
uvx ruff check hololinked. - Unit/Integration tests are recommended to be added for any new feature or bug fix. These tests can be run with
python -m unittestunder thetestsdirectory. - The CI pipeline currently enforces codestyle checks and tests, therefore steps 4 & 5 must be completed before making a pull request.
- Once you are done with your changes, make a pull request to the main repository. Your changes will be reviewed in detail and any review comments that may be added need to be resolved as well. When requirements are met and the pipeline passes, commits will be squashed and merged to the main branch.
- For AI generated code, please make sure to review it properly. You need to understand the code that you write or submit. Same applies to documentation, comments etc., please write them only to the extent you would be willing to read them later, not to bloat them with autogenerated text. A thumb rule is, if you cannot review your own generated code, I am not going to do it either. Submit only what you will review.
There are also other repositories which can use your skills:
- An admin client in react
- Documentation in mkdocs which needs significant improvement in beginner level docs which may teach people concepts of data acquisition or IoT, Docstring or API documentation of this repository itself
- Examples in nodeJS, Dashboard/PyQt GUIs or server implementations using this package. Hardware implementations of unexisting examples are also welcome, I can open a directory where people can search for code based on hardware and just download your code.
Do feel free to reach out to me at email or in discord (links in README). I will try my very best to respond.
Nevertheless, one may also refer the available how-to section of the Documentation. If the documentation is insufficient for any reason including being poorly documented, one may open a new discussion in the Q&A section of GitHub discussions.
For questions related to workings of HTTP, JSON schema, basic concepts of python like descriptors, decorators etc., it is also advisable to search the internet for answers first. For generic questions related to web of things standards or its ideas, it is recommended to join web of things discord group and community group.
If you believe your question might also be a bug, you might want to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. If an issue is not found:
- Open an Issue.
- Provide as much context as you can about what you're running into.
- Stack trace (Traceback)
- OS, Platform and Version (Windows, Linux, macOS)
- Version of python
- Possibly your input and the output
- Can you reliably reproduce the issue?
One may submit a bug report at any level of information, especially if you reached out to me upfront. If you also know how to fix it, lets discuss, once the idea is clear, you can fork and make a pull request.
Otherwise, I will then take care of the issue as soon as possible.
You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to info@hololinked.dev.
A simpler model is used roughly based on this article -
- main branch is where all stable developments are merged, all your branches must merge here.
- A specific release is tagged and not created as its own branch.
- other branches are feature or bug fix branches.
This guide is based on the contributing-gen. Make your own!