Contributing

Thank you for helping. Before you start on something big, say what you have in mind in Ideas, so we can agree on the shape first. Ask questions in Q&A, and report bugs in Issues.

Build from source

You need Elixir 1.18 or newer and Erlang/OTP, plus a C compiler (Xcode's command line tools on a Mac) for the SQLite driver.

git clone https://github.com/kyroco/vitalaize.git
cd vitalaize
mix deps.get
cp settings.example.exs settings.exs     # then edit it
MIX_ENV=prod mix release
_build/prod/rel/wallboard/bin/wallboard start

It prints the address to open, like Board is up: http://192.168.1.20:4747/. To keep it running (it starts when you log in and again if it ever stops), run scripts/login-item.sh on on a Mac or scripts/systemd.sh on on Linux; off turns either one off.

Everything specific to you lives in settings.exs. At the least, set your repositories (github.repos) and their workflow file names, and claude.config_dirs if your Claude folder is not ~/.claude. Anything you leave out uses its default. Settings lists them all.

While you work on the code, mix run --no-halt runs the board straight from the source.

To build the Mac app and its installer yourself: macos/build.sh. With an Apple Developer ID it signs them, and with --notary-profile NAME it also notarizes them (see the top of the script).

Checks before you push

GitHub runs these on Linux and macOS for every pull request and every push to main, and fails on bad code style or any compiler warning. Run the same ones first:

mix format --check-formatted
MIX_ENV=test mix compile --warnings-as-errors --force
mix test --warnings-as-errors

mix format fixes the style for you.

Dependency audit

CI also checks the packages VitalAIze uses. It fails when mix.lock is out of date, and when a package has a known security hole or was retired by its author. Run the same two commands first (they need Hex 2.5 or newer):

mix deps.get --check-locked
mix hex.audit

Changing the collector's messages

The messages a collector sends the hub are defined in priv/protos/collector.proto. The Elixir code built from that file is saved in the repo, so a plain build needs nothing extra. If you change the file, install protoc, then build the code again and format it:

mix escript.install hex protobuf 0.17.0
protoc --elixir_out=plugins=grpc:lib -I priv/protos collector.proto
mix format

Security scan (Sobelow)

CI runs Sobelow, a security scanner for Phoenix apps, on every pull request, and fails on anything it finds at medium confidence or above. Run it yourself before you push:

mix sobelow --config

That reads its settings from .sobelow-conf at the repo root. CI does not read that file: it passes the same settings itself (the SOBELOW line in .github/workflows/ci.yml), so a pull request cannot turn the check off. A finding that is not a real problem is skipped in both places, with a one-line comment saying why. # sobelow_skip comments in the code are ignored. Findings on main, and on pull requests from a branch of this repo, also show under the repo's Security tab.

Dependency updates

Once a week, Dependabot opens one pull request for newer Elixir packages and one for newer versions of the actions CI uses. They go through the same checks as any other pull request.

Pull requests

• Keep each pull request to one change, and say in its description what problem it solves and how you checked it.
• All the checks above must pass before it can merge.
• Robert Sfeir reviews every pull request from outside the team, and may ask for changes before it merges.
• Write for people who are not experts: plain English, short sentences. That goes for code comments, the README and this wiki.

Making a release

1. Set the version in mix.exs, merge it, and push a tag for it from main, like git tag v0.3.0 && git push origin v0.3.0.
2. GitHub builds both Linux downloads on Ubuntu 22.04 (Intel and ARM), checks that each one starts, and puts them on a draft release for that tag.
3. Build the Mac installer on a Mac with macos/build.sh (it needs the Developer ID), add it with gh release upload v0.3.0 VitalAIze-0.3.0.pkg, then write the notes and publish the draft.

Push the tag before making the release, so there is only the one draft. A published release only gets Linux downloads it does not have yet; to replace one, delete it from the release first.

License

Apache License 2.0. See LICENSE and NOTICE. By sending a pull request, you agree that your change is licensed the same way.