There are several ways of contributing to this project, including:
- Providing new service providers
- Updating or improving the documentation
- Helping answer/fix any issues raised
- Join in with the Home Assistant Community discussion
In GitHub, navigate to the repository homepage. Click the fork button at the top-right side of the page to fork the repository.
Navigate to your fork's homepage, click the code button and copy the url.
On your local machine, open a terminal and navigate to the location where you want the cloned directory. Type git clone and paste in the url copied earlier. It should look something like this, but with your username replacing YOUR-GITHUB-USERNAME:
git clone https://github.com/YOUR-GITHUB-USERNAME/hacs_waste_collection_scheduleBefore making any changes, create a new branch to work on.
git branch <new_branch_name>For example, if you were adding a new provider called abc.com, you could do
git branch adding_abc_comFor more info on forking/cloning a repository, see GitHub's fork-a-repo document.
There are 2 ways to add support for a new service provider:
-
This is the preferred way of adding support for a new service provider, but only works if the service providers offers a so called "ical / webcal subscription" or at least a static link which doesn't change over time to an ICS file.
-
This is the fallback if the preferred way via the generic ICS source doesn't work.
If you want to contribute a new source, these existing implementations can be used as practical examples:
- HTML parsing (BeautifulSoup / bs4):
birmingham_gov_uk.py - ICS-based implementation:
stadtreinigung_hamburg.py - JSON/API implementation:
toronto_ca.py
If you're using an AI assistant (Claude Code, Cursor, codex, Aider, GitHub Copilot, etc.) to draft a contribution, point it at the project-specific instruction files in the repo:
CLAUDE.md— read by Claude Code. Project overview, source module contract, common pitfalls, and pointers to the specialised agents and slash commands.AGENTS.md— read by Cursor, codex, Aider, and other tools that support theAGENTS.mdconvention..github/copilot-instructions.md— used by GitHub Copilot.
All three capture the source module contract, the lint/test commands, and the patterns that reviewers consistently flag — they help the assistant produce a PR that's much closer to mergeable on the first pass.
Claude Code users: the repo also ships with specialised agents and a slash command to walk you through implementing a source from scratch:
/new-source— orchestrated walkthrough: confirms the provider isn't already supported, identifies the best data feed (ICS / JSON API / HTML / PDF), generates the source module + doc page, lints, and runs the test cases. Reduces the round-trip with reviewers.- The underlying agents (
source-investigator,source-implementer) can also be invoked directly if you prefer step-by-step control. See.claude/agents/for the full list.
Having completed your changes, sync your local branch to your GitHub repo, and then create a pull request. When creating a pull request, please provide a meaningful description of what the pull request covers. Ideally it should cite the service provider, confirm the .py and doc/source/<name>.md files have been added, and include the output of the test_sources.py script demonstrating functionality. Note: README.md and info.md are auto-generated by CI after merge — do not edit or include them in your PR. Once submitted a number of automated tests are run against the updated files to confirm they can be merged into the master branch. Note: Pull requests from first time contributors also undergo a manual code review before a merge confirmation is indicated.
Once a pull request has been merged into the master branch, you'll receive a confirmation message. At that point you can delete your branch if you wish.
To route source-related bug reports to the right maintainer, this repository uses a generated owner mapping file:
.github/source_owners.json(generated byupdate_docu_links.py— do not edit manually)
A GitHub Action (.github/workflows/notify-source-owners.yaml) reads the Source Name field from [Source Defect] bug reports and pings plus assigns the configured owner(s) for that source.
Per-source owners for Python sources are defined via the optional SOURCE_CODEOWNERS variable in the source file:
SOURCE_CODEOWNERS = ["@your-github-handle"]Per-provider owners for ICS YAML providers are defined via the optional codeowners key in the YAML file:
codeowners:
- "@your-github-handle"Every handle must start with @ — the CI test suite enforces this. update_docu_links.py normalises handles (prepending @ if missing) before writing source_owners.json.
If you add or maintain a source, strongly consider adding your GitHub handle to take ownership. You will be automatically notified and assigned on bug reports for that source, making it easier to keep your source healthy.
Non-code contributions are welcome. If you find typos, spelling mistakes, or think there are other ways to improve the documentation please submit a pull request with updated text. Sometimes a picture paints a thousand words, so if a screenshots would better explain something, those are also welcome.
Open-source projects are always a work in progress, and issues arise from time-to-time. If you come across a new issue, please raise it. If you have a solution to an open issue, please raise a pull request with your solution.
To help prevent duplicate work, we encourage contributors to self-assign issues they are actively working on (e.g. adding a specific waste collection source). To assign an open issue to yourself, simply leave a comment on the issue containing /assign-me — our GitHub automation will then assign it to you. Comment /unassign-me to release it again.
The main discussion thread on Home Assistant's Community forum can be found here.