Contributing

LokalBoards is MIT-licensed and the repository is on GitHub. Bug reports, fixes, features and corrections to these pages are all welcome — a report that says exactly what you did and what happened instead is worth as much as a patch.

The same ground is covered by CONTRIBUTING.md in the repository, which is the copy you will have to hand while working.

Setting up

It is an ordinary Nuxt application. You need Node 22 — the version CI runs — and a MySQL 8+ you can point at. An empty database is enough: the tables are created on first start and every later start applies whatever is outstanding.

git clone https://github.com/florian-strasser/LokalBoards
cd LokalBoards
npm install

Put your database credentials in a .env.local — the variables are the ones listed under Getting started — and start the dev server against it:

npx nuxt dev --dotenv .env.local

Keeping local settings in .env.local rather than .env is worth the habit: the file is ignored by git, so a real password cannot be committed by accident.

The tests

There are four suites, and which one you need depends on what you touched.

Unit tests are fast and need no database. This is what gates every pull request:

npm test

The other three run real code against a real MySQL. Point them at a throwaway database — they truncate tables, so never at anything you would miss:

export TEST_MYSQL_HOST=127.0.0.1
export TEST_MYSQL_USER=root
export TEST_MYSQL_PASSWORD=yourpassword
export TEST_MYSQL_DATABASE=lokalboards_test

npm run test:integration   # the data layer against the database
npm run test:e2e           # the built server, over HTTP
npm run test:browser       # two real browsers on one board

test:browser is the interesting one: it drives two Chromium sessions against the same board to check that what one does shows up for the other, which is the promise the whole product rests on and the one thing no unit test can make.

It needs npm run build first, and it serves the built app on port 3000 — so stop anything else you have running there. Outside CI it will happily reuse a server it finds on that port, which means a dev server left running gets tested instead of your build.

Add or update tests for behaviour you change. Anything touching authorization, sessions or API keys should keep the coverage it has.

Changing the database schema

The schema is a list of migrations in app/lib/databaseSetup.ts, applied once at startup. To change it, append a migration to the array with an up(db) function — for example 0017_add_x. Never edit or delete one that is already there: it has already run on other people's installations, and the runner has no way to notice it changed.

Opening a pull request

  • npm test passes, and the database suites too if you touched that code.
  • npm run build succeeds.
  • There is a CHANGELOG.md entry under the unreleased version saying what changed and why.
  • New behaviour has tests where that is practical.
  • The code reads like the code around it.

CI then runs the unit suite, a production build, both database suites against a MySQL service container, the browser tests, npm audit, and a build of the Docker image — the last one because a Dockerfile regression is invisible until somebody pulls the image.

Security

Please do not open a public issue for a vulnerability. The security policy says how to report one privately.