Developer Guide

Developer Guide

This page exists so contributors do not accidentally improve the project into a broken state.

Development workflow

Recommended flow:

main -> create branch -> make changes -> open PR -> review CI -> merge

Branches and pull requests

Do not work directly on main if the change is non-trivial.

Use a topic branch:

git checkout -b my-change

Then open a Pull Request.

CI

The repo includes GitHub Actions in .github/workflows/pylint.yml.

Current workflow:

• runs on push
• runs on pull_request
• installs requirements.txt
• runs ruff
• runs black --check
• runs pytest

Important caveat

Those commands currently end with || true, which means CI is informational, not a strict gate. Read the logs. Green does not always mean good. Humans love this kind of trap.

Code owners

Core files are protected with CODEOWNERS for review routing.

Protected areas currently include:

• main.py
• rotation_engine.py
• db_manager.py
• display_manager.py
• selected API modules

Safe to modify

Good places for beginners:

• apis/*
• fallback content text
• provider normalization logic
• documentation
• wiki pages
• .env.example

Sensitive modules

Treat these as dangerous until you understand the full runtime:

• rotation_engine.py
• display_manager.py
• db_manager.py
• main.py

Why:

• rotation_engine.py defines slot identity and persisted content selection
• display_manager.py defines timing, rendering, preview behavior, and matrix output
• db_manager.py defines schema and connection behavior
• main.py ties together scheduling, providers, and display

Before changing core code

Check all of these:

• Does the category order still work?
• Does the project still start with an empty DB?
• Does --simulate still work?
• Does --once still behave predictably?
• Does CI still run?
• Did you change payload keys used by the renderer?

Adding a new category

A real category addition usually requires coordinated changes in:

1. rotation_engine.DISPLAY_SEQUENCE
2. main.build_content_for_now()
3. main.print_payload()
4. display_manager.py rendering/display code
5. possibly db_manager.py if persistence is required

Do not add a category in only one layer. That is how you manufacture runtime bugs with confidence.