> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tomorrowos.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

# Contributing to TomorrowOS

Thanks for helping build TomorrowOS.

TomorrowOS is an open-source SDK, server and on-device runtime for building digital signage software across supported screen platforms.

The project benefits from people who understand how signage behaves in the real world: developers, integrators, CMS vendors, hardware specialists, operators and platform experts.

## Ways to contribute

You can contribute by:

* Improving the SDK, runtime or server
* Adding or improving platform adapters
* Documenting model and firmware-specific behaviour
* Adding compatibility and certification test cases
* Improving documentation and examples
* Building integrations and developer tools
* Reporting playback, packaging, synchronisation or device-control issues
* Sharing reproducible platform quirks and fallback behaviour

Not every contribution needs to be code. Clear testing notes, hardware findings and documentation improvements are valuable.

## Before you begin

For small fixes, documentation updates and clearly scoped improvements, you can open a pull request directly.

For larger changes, new platform support or changes to the public API, please open a GitHub Discussion or Issue first so the approach can be agreed before significant work begins.

Before submitting a contribution:

* Search existing Issues and Discussions
* Keep the change focused
* Explain the problem being solved
* Include testing notes where possible
* Update documentation when behaviour or the public API changes
* Do not include secrets, private keys, customer data or proprietary SDK material

## Platform and capability contributions

Real-world platform knowledge is one of the most valuable parts of TomorrowOS.

When documenting a capability, use one of the following core statuses:

| Status        | Meaning                                         |
| ------------- | ----------------------------------------------- |
| `supported`   | Works through the standard TomorrowOS interface |
| `partial`     | Works with known limitations                    |
| `unsupported` | Not available on the tested platform            |
| `unknown`     | Not yet tested or confirmed                     |

Record platform conditions separately where relevant:

* Hardware model
* Firmware or operating-system version
* Browser engine version
* Required native bridge or adapter
* Known safety or reliability concerns
* Fallback behaviour

This keeps capability status simple while preserving the detail needed for reliable deployments.

## Evidence matters

Capability claims should include as much supporting information as possible:

* Platform and OS version
* Device model
* Firmware version
* Browser engine version, where relevant
* Test method
* Expected result
* Actual result
* Known limitations
* Fallback behaviour
* Logs, screenshots or sample media where useful

Example:

```json theme={null}
{
  "feature": "playback.video.h264",
  "platform": "tizen",
  "status": "partial",
  "testedModels": ["QM43C"],
  "testedVersions": ["Tizen 7.0"],
  "limitations": [
    "Codec and playback behaviour may vary by model and firmware."
  ],
  "fallback": "Display the configured fallback image if video validation or playback fails."
}
```

Treat this example as guidance unless the repository defines a formal capability schema elsewhere.

## Pull request checklist

Before submitting a pull request, confirm that:

* [ ] The change is clear and focused
* [ ] The problem and proposed solution are explained
* [ ] Relevant tests have been added or updated
* [ ] Documentation has been updated where needed
* [ ] Capability claims include evidence where possible
* [ ] No secrets, customer data or proprietary material are included
* [ ] The change preserves a clear and consistent developer experience
* [ ] The change aligns with the current project direction

## Development principles

TomorrowOS should remain:

* Simple for developers to understand and adopt
* Honest about platform and hardware limitations
* Safe and predictable for device control
* Reliable in real-world signage environments
* Useful across different products and deployment models
* Open enough for the industry to build on
* Stable at the core while allowing the ecosystem to expand

The community contributes. Maintainers protect the quality, stability and direction of the core.

## Reporting security issues

Do not report security vulnerabilities through a public Issue.

Follow the process described in [SECURITY.md](./SECURITY.md).

## Community standards

All contributors must follow the [Code of Conduct](./CODE_OF_CONDUCT.md).

Project decision-making and maintainer responsibilities are described in [GOVERNANCE.md](./GOVERNANCE.md).

## Contribution licence

By contributing to TomorrowOS, you agree that your contribution may be released under the project's Apache License 2.0.