Skip to content

Contributing to Glasshouse

Contributions are welcome. This guide outlines how to propose changes, write compatible code, and review pull requests.

Core principles

  • You own the glass: The project exists to give owners direct control over their TV without vendor lock-in, cloud dependencies, or tracking. No telemetry or analytics are collected.
  • Keep the TV lightweight: The TV's onboard CPU and RAM are shared with video decoding and system processes. Code running on the TV must remain fast, lean, and free of unnecessary background work.
  • Zero runtime dependencies: The on-TV server runs with no npm packages installed on the device.

Working conventions

Never push to main

Always work on a branch and submit a pull request:

  1. Create a branch from main.
  2. Make changes, keeping commits focused and logically distinct.
  3. Push the branch to your fork or the repository.
  4. Open a pull request against main.

If a pull request needs follow-up adjustments, push additional commits to the existing branch rather than opening a new pull request for the same work.

Commit messages and PR descriptions

Focus on clarity and readability. Clearly state what changed and why, keeping pull request descriptions concise and focused on the context reviewers need.

If you are using AI coding assistants or automated agents, ensure they adhere to the repository conventions in CLAUDE.md.

Code reviews

We prefer code review comments to follow the Conventional Comments standard (e.g. praise:, suggestion:, issue:, nitpick:, question:). This keeps feedback constructive, actionable, and makes it clear whether a comment is blocking or an optional suggestion. Refer to conventionalcomments.org for the complete specification and examples.

Environment and compatibility

Strict ES5 for on-TV code

The server runs on the TV under Node.js 0.12 (on webOS 3.x and 4.x models). All files executing on the TV must remain strict ES5:

  • server/tvweb.js
  • server/lib/*.js
  • server/assets/dashboard.html
  • server/assets/setup.html
  • server/assets/setup-phone.html

Avoid all ES6+ constructs in these files: no const or let, arrow functions, template literals, classes, default parameters, destructuring, promises, async/await, for...of, or ES6 built-in methods (Object.assign, Array.prototype.find, etc.).

Run python3 scripts/check-es5.py to verify compliance.

Modern JavaScript in browser dashboards

Modern JavaScript (ES6+) is permitted exclusively in client-side code running in modern desktop/mobile browsers:

  • server/assets/ui.html
  • server/assets/ui/*.js

Adding new server assets

The deploy script (server/deploy.sh) maintains an explicit list of files copied to the TV via SSH (FILES). Any new module or asset in server/ required by the TV must be added to this list. scripts/check-drift.py verifies that all files on disk match the deploy manifest.

Localized strings

All user-visible text on the dashboards is keyed for localization:

  • In HTML: data-t="section.key"
  • In JavaScript: t('section.key', 'Default English string', { vars })

Strings are cataloged in server/assets/i18n/. Refer to Translating the dashboards for full formatting rules. Run python3 scripts/check-strings.py to ensure all strings are keyed and translated without drift.

Running tests and verification

Before opening a pull request, run the test suite and validation scripts locally:

# Run all unit and integration tests
node test/run-all.js

# Type checking
npx tsc

# Syntax and architecture checks
python3 scripts/check-es5.py
python3 scripts/check-drift.py
python3 scripts/check-strings.py
python3 scripts/check-ui-ids.py
python3 scripts/check-screensavers.py
python3 scripts/check-module-calls.py
python3 scripts/check-entity-stability.py
python3 scripts/check-entities.py --stats test/fixtures/stats-b8-webos4.json

# The release's updater can still install the change on TVs already out there
node scripts/check-upgrade.js

All automated checks must pass cleanly.

Testing on a real TV

The automated checks run the server's code, not the TV. LG's services, the picture and sound pipeline and the start-up sequence behave differently between models and webOS versions, and only a real TV shows how a change behaves there. Before asking for a review:

  • Deploy the change to a rooted TV with server/deploy.sh <tv-ip>, and use what it changes the way someone would: on the web dashboard, in the TV app, or from Home Assistant.
  • Check that what's around it still works. The TV still shows its inputs, sound still plays, and the dashboard keeps updating.
  • Restart the server or the TV if the change affects start-up, the boot hook (server/50-tvweb.sh), or anything that runs only once.
  • Mind older TVs. On webOS 3 and 4 the server runs on Node 0.12, and a call newer firmware accepts may not exist there. If you can only test on one generation, say which.

Testing details in the pull request

Add a short Testing section to the pull request description:

  • the TV's model and webOS version, for example "OLED42C24LA, webOS 9.2";
  • what you did and what you saw;
  • what you didn't test, such as other webOS versions or something that needs hardware you don't have.

For example:

## Testing

- OLED42C24LA, webOS 9.2: hid and unhid three tiles from the Apps tab. Each took
  about 4 seconds, and HDMI 2 kept its picture and sound throughout.
- Not tested on webOS 4 or on webOS 10 and later.

If you can't test on the right TV

If you don't have a TV to test on, or the change affects TVs you don't have, say so in the pull request and ask for testers. A maintainer will label it testers wanted, where people with other TVs look for things to try.

Help by testing on your TV

Some changes can only be checked on TVs the maintainers don't have, such as newer or less common models. If you have a rooted LG TV, you can help without writing any code: pull requests and issues labelled testers wanted say what to run and what to send back.