Geocaching integration feature updates

[marc7s]

Proposed change

This update adds several new features to the Geocaching integration, enabled by the release of version 0.3.0 of the geocachingapi package, changelog. It adds support for Geocaches and Trackables, creating a device for each cache or trackable containing the relevant entities for each item. Here is an example of a device generated for a Trackable, with entities related to that device:

We have provided a README for the integration, containing some example templates for presenting caches and trackables on a dashboard.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• We (devs of this feature update) are first time Home Assistant contributors, and are therefore new to the system and the development environment. This feature update was developed by @marc7s, @belgien, @ClumpyAbbe and @hulkper, but the integration was created by @Sholofly and @reinder83
• Nearby caches creates entities, but we are unsure exactly how Home Assistant handles this. Should the API response be different, we do not know whether new entities will be created and what happens with the old ones
• A part of a test was commented out since adding the additional configuration step caused it to break. We do not have experience with creating config flow tests in Home Assistant and did not know how to fix this
• The external package has a new dependency, reverse_geocode. We are not sure how this is handled in HA, but we did not add that dependency to the requirements in the manifest. We recloned the repository and rebuilt the dev container and it still worked, so we assume dependencies of requirements are installed automatically
• We have documented the code using comments, and in the API update PR, but we have not made changes to the docs repository
• Link to new API update with explanations and screenshots: Updates to support Geocaching Home Assistant integration feature updates Sholofly/geocachingapi-python#23

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

Stale

[joostlek]

Please split the PR up into smaller parts and try to keep PRs scoped, as in, not bigger than needed.

So I would suggest first opening a PR to bump the library and then go from there

[marc7s]

@joostlek The new library version is connected to the changes in this PR. They were developed alongside each other, bumping the library version without updating the integration code will not do anything as the old code does not use the new features of the library. I have not tested using the old code with the new library so it might even cause issues.

How do you propose we split the PR? I cannot think of any reasonable splits myself, since the new version is tested as a whole and not in small parts.

[joostlek]

bumping the library version without updating the integration code will not do anything

But that is fine, that means that when that is one PR, that PR has everything it needs to support the new version.

This PR is too big to review. The bigger they are, the slower they get in.

You can add the base entity in a separate PR, do the other platform improvements in separate PRs, add new platforms in a separate PR. But I haven't looked in the code in depth as it does too much.

[reinder83]

I wonder if the codeowners need to be changed, not all contributers have to be owner

[marc7s]

Home Assistant automatically changed that file, but we can remove it if you would like

[reinder83]

Ah that's why, it's fine by me, I dont know what is commonly done

[reinder83]

Overall it looks good to me, very cool new additions, but I cannot review the integration part, maybe someone with more experience in this could review this.
The only thing I wonder is if we should add more codeowners?

[joostlek]

I mean if there are people who want to step up and help with the integration and issues, they are free to do so. We don't really have any process in place with stale codeowners or too many codeowners

[marc7s]

@joostlek I understand where you are coming from, but splitting it would mean we need to test every part all over again to ensure we don't break anything.

The PR only really has two parts:

1. Add a new configuration step to the integration setup, for configuring the new sensors
2. Add a few new sensors

Most of the code is just adding the new sensors, with abstractions to be able to reuse the code for the sensors. So should we do a PR with just the entity abstractions first? The sensors themselves are small, they just leverage the abstractions.

I think it would be pretty confusing adding a bunch of structure for just a single sensor or so. But if that confusion is worth it to have a smaller PR then I guess it would be possible. But again, I would need to retest everything again to make sure it does not break.

[joostlek]

This PR can be split up in at least 5 or 6 PRs.

The thing is, if you didn't change existing code or config, it should be fine.

The downside with big PRs is, if there is something wrong in the base of that PR, the rest of the PR needs to adjusted too. If the PR is smaller, that is easier as you don't have to move that much code around.

And I don't mind to give directions on how to best get it in, and I am sure that others are also willing to help testing, but we should adhere to the guidelines we set to the project. If every integration gets one of those PRs every 6 months I would scream.

[Sholofly]

Hi @marc7s, It looks like this PR is not coming through due to the size. I probably can help testing if you split it up. Tell me what I can do!

[marc7s]

Hi @marc7s, It looks like this PR is not coming through due to the size. I probably can help testing if you split it up. Tell me what I can do!

I have now spent a few days separating the code into several PRs, which I will start opening now. The first is #139878

I have tested each PR somewhat, but since I know the code worked as a whole there may be some issues in a specific phase that gets fixed by a later PR. But I tried configuring the Geocaching integration for each PR, and it seemed to work for all PRs

I removed the nearby caches feature from the split up phases, as the implementation was not 100% with the entities not being dynamically generated.

FYI @joostlek

[frenck]

Alright, since the splitting has started, I'll go ahead and close this one up to keep our queues clean.

Please make sure not to stack up the PRs, as that just causes noise. I've closed the others for that reason (let's re-open and rebase them when they are relevant again).

../Frenck