Skip to main content

Contributing to ApexOS

Everyone is welcome to contribute to ApexOS. Whether you want to integrate a device that isn't supported yet, improve the frontend, or package a new add-on, this section explains how the process works.

The repositories​

Development happens in the open under the apexinfosysindia GitHub organization. The three repositories most contributors touch are:

RepositoryWhat lives there
coreThe Python backend: the apexos package, all integrations (apexos/components/), and the test suite.
frontendThe TypeScript/Lit web interface, built with Yarn workspaces.
addonsContainerized add-ons (Mosquitto, Samba, SSH, VS Code, Zigbee2MQTT, Matter Server, and more), one directory per add-on with its config.yaml, Dockerfile, and docs.

The workflow: fork and pull request​

The process is straightforward:

  1. Fork the repository you want to work on.
  2. Write your change — a new integration, a bug fix, a sensor, a notification service.
  3. Make sure the tests pass (see Testing).
  4. Open a pull request against the main branch of the upstream repository.

Direct pushes to main are not accepted; all changes land through reviewed pull requests.

Review and required checks​

Every pull request runs the CI pipeline before it can merge. For core, that includes:

  • prek — the pre-commit hook runner (Ruff lint + format, codespell, yamllint, prettier, and more).
  • mypy and pylint — static typing and lint gates.
  • apexfest — validates integration manifests and generated files.
  • pytest — the test groups relevant to the files you changed (the full suite plus MariaDB/PostgreSQL recorder runs on full-suite triggers).

A maintainer reviews the change once checks are green. Keeping pull requests small and focused is the single best way to get a fast review.

Contributor License Agreement​

By contributing, you certify the terms of the project's CLA. In short, you certify that:

  • the contribution was created by you (in whole or in part) and you have the right to submit it under the Apache 2.0 license; or
  • it is based on prior work under a compatible open-source license that permits you to submit it, with your modifications, under Apache 2.0; or
  • it was provided to you by someone who certified the above, and you have not modified it;

and you understand that the project and your contribution are public, and that a record of the contribution — including personal information you submit with it — is kept indefinitely and may be redistributed under the project's licenses.

The CLA is based on the Developer Certificate of Origin, adapted to explicitly use the Apache 2.0 license. You sign it by submitting your first pull request to a repository under the apexinfosysindia organization.

Code of conduct​

All ApexOS community spaces follow the project's Code of Conduct, based on the Contributor Covenant. Read it before participating — it applies to issues, pull requests, and discussions alike.

Feature suggestions and issues​

Getting help​

Where to go next​