Generic info approach of contributing to Plugwise

For those that hate to read manuals and/or just want to change a few lines of code:

If you are really keen on getting started, you don't need all of the below to help out. If you decide to 'just change some lines of code' on whatever (probably HACS) deployed on your testing/production HA. Ensure you can get to your local code (i.e. in order of preference install the Visual Studio Code add-on, install the terminal AddOn and use it interactively (but you shouldn't :)) - use the before ensuring SSH access) and just have a go at whatever is in your /config/custom_components/plugwise_usb-beta directory. Be sure to restart your HA environment between edits and just create an issue (if a PR is a to steep hill for now) telling us which lines/changes you made.

What do you need: and don't get overwhelmed, I'm not the most concise of typing people.

• Enjoy learning things and don't get discomforted by people being blunt. I don't think either of the (current/original) three maintainers is harsh, but when you get to a certain level of interaction with (other) projects, people might be very honest/blunt/short in their answers, that is just because they have a lot on their plate, not to scare you.
• A development environment (i.e. a virtual machine or just your desktop/laptop) - your HA (production) environment isn't the best place :)
• A python interpreter on that environment, although most (Linux) distributions come with one, it's wise to ensure you are on the latest release though (so do install (time of writing) python3.12). That does not require to be your main version, python is very capable of running in a venv (virtual environment).
• Access to GitHub, you're here, so done :)
• A editor (preferably an IDE) is very helpful, decide for yourself, but Visual Studio Code seems to be the main preference nowadays. It also supports handling git for you which might be beneficial in saving time on learning command-line commands.
• A fork (see 1 in the picture) of the repository you are on (assuming you read this starting out, you won't be able to 'change' (we call that commit) things right away to plugwise/plugwise_usb-beta or plugwise/plugwise_usb. Forking is easy, just go the the repository main url and click the 'fork' button right-top and you'll get a copy in your own (username) list of repositories.
• Knowledge of using git (as. in the command) is highly beneficial, just run over some of the tutorials by Atlassian, they are decent.

Depiction of where to find the fork (for above) and clone-uri (below):

So what else? Just a very rough summary of what we have on our machine:

• /home/myuser/github/plugwise/ directory where we git cloned the repositories in. I use ssh but you can use the https as well. Just go to your fork of the repo and look up the green 'code' button (2), ensure you are on local (3) and choose between ssh and https, if unsure, go for https for now! Copy that url and while in your plugwise folder, git clone <paste> and follow along.
• As you will be a contributor (for now) and have your own repo, you'll might want to follow along. When cloning is successful, change to said directory and git remote add upstream https://github.com/plugwise/plugwise_usb-beta/ (i.e. for the custom component).
• For those pretty familiar with git, but not with working in a repo; assuming you are in main in your fork, you can now git fetch upstream; git rebase upstream/main; git push origin main to fetch updates from the plugwise repo's into your own main branch. If you need help, just give a heads-up and we'll be able to help you out.
• Final steps before getting going; we've added 'setup scripts' (for Linux/Mac) to get things rolling.
  • Assuming you are in your {..}/plugwise_usb-beta directory, ensure you have the venv there (i.e. run python3.12 -m vent vent and activate it source venv/bin/activate
  • In both repositories you'll find setup.sh and in the module also setup_test.sh scripts. Again assuming you are in the custom module, just run the scripts/setup.sh (while in your activated venv)
  • Give it a whirl to ensure everything is ready, run scripts/core-testing.sh which will take some time (as it will clone the full HA repository as well). If you see some (green) checkmarks, things like code coverage and hastiest Validating all kinds of things your are in a good spot

Now for the good part, actually trying stuff out :) #incomplete needs thinking cap on how to best deploy 'your fork'/code in your local environment.

• Create a new local branch (or do the tutorial on how git branching works). Change parts of the code you like and commit them. Your tool of choice will give you a link to 'create your first PR' and we'll discover together from there.
• Try out things locally, even though your raspberry or VM is not the best development environment. And still, your local management team (i.e. partner/kids/etc.) might not be keen on you 'tinkering in production', you still could. Assuming you now used HACS to deploy the module, you can override this again but this will involve some tinkering and/or command line work.
  • TODO/INCOMPLETE; either with terminal add-on rename/remove HACS deployment of plugwise_usb-beta and 'git clone' your fork and change to the correct branch -/- remove current plugwise repo-url from HACS and replace with your own (requires releasing though so might also not be the best)

Reading material

• https://developers.home-assistant.io/docs/creating_component_index as a starting point, but the HA developers site has more or less everything you need (from figuring out which device_class to use, why you can't set custom icons on an existing device_class, etc.)
• Using find in Visual Studio Code, or assuming you are on Linux or a Mac, grepping through code tutorial might be a very convenient way to figure out how someone else did it. If you forked/cloned and used the core-testing.sh script you have the latest full HA code already at hand. It's in the ha-core directory of your custom component :) (And no you don't need this on your testing/production environment, it's rather large)