Project

Contributing

A small project with a few strong opinions, all in one place so you do not have to guess them from a review.

The short version: anything that changes behaviour comes with a test, comments explain why rather than what, and a pull request says what you actually verified.

Before you write code#

Open an issue first for anything substantial. A bug fix or small improvement can arrive as a pull request. A new feature, a schema change, or anything touching matchmaking is worth discussing first, because a lot of design reasoning lives in the docs and it is a shame to find out after you have written it.

If you are touching	Read first
Anything at all	Architecture
Matchmaking, queue, parties	Matchmaking & parties
Ratings, stats, the leaderboard	Rating
Anything the CS2 server sends	MatchZy integration
The website or launcher UI	Design system
Deployment and configuration	Windows · Linux · Configuration

Looking for something to do? The known gaps are an honest list of what is wrong today.

Getting set up#

You need Docker, the .NET 10 SDK, Node.js and, for the launcher, Rust. The Quickstart walks through it.

Terminal

docker compose up -d                  # PostgreSQL
cd backend/Flicked.Api && dotnet run  # API on http://localhost:5165
cd launcher && npm install && npm run tauri dev

Tests#

Terminal

dotnet test backend

About 70 tests in roughly 30 seconds. They need Docker running, because they run against a real PostgreSQL database, flicked_test, which the fixture creates and migrates itself.

Why real Postgres and not an in-memory provider#

Because the most important things in this codebase are races, and an in-memory provider cannot express them:

the server pool hands out servers with FOR UPDATE SKIP LOCKED, so two matches filling at the same instant get different servers;
two party invites accepted simultaneously are resolved by a unique index refusing the second insert;
a match is finished by a conditional UPDATE, so a duplicate series_end, which the plugin genuinely sends, changes nothing the second time.

A test suite that cannot fail on any of those is decoration.

When a test is expected#

If your change could break in a way a human would only notice during a match, write the test that notices it first.

Needs a test

New endpoints; changes to matchmaking, rating or the pool; anything concurrent; anything parsing what the CS2 server sends; every bug fix (failing before, passing after).

Does not

Documentation, copy changes, styling, and pure refactors where existing tests already cover the behaviour.

Write the test at the level the bug lives. Most of the suite tests services against a real database, because that is where the logic is. For arithmetic, a pure unit test is better: see RatingTests.cs.

The other checks#

Terminal

cd launcher && npx tsc --noEmit        # launcher types
cd launcher/src-tauri && cargo check   # launcher Rust
cd website   && npx next build         # website builds
cd dashboard && npx next build         # dashboard builds

Style#

Comments explain why, not what. This is the one thing most likely to come up in review. The code says what it does; a comment earns its place by explaining a decision, a trade-off, or a trap.

Example

// Bad: restates the code
// loop over the players and set their team

/* Good: explains the decision
   Parties are placed whole rather than drafted player by player, because the
   entire point of a party is landing on the same side. */

Read a few files near yours before writing, and match their density and voice. Naming and formatting follow whatever the surrounding file does; there is no separate style guide to memorise.

Commits and pull requests#

Conventional commits, with a scope:

git log

feat(backend): the queue holds parties
fix(launcher): one build-time API address, not two
docs(roadmap): describe what shipped, and what is still wrong
test(backend): the rating maths, its edges, and the same match twice

In the pull request, say what you verified, something like:

Ran dotnet test backend, 70 passed. Checked cargo check and tsc. Did not test against a real CS2 server.

That last line is the important one. Never say something ran when it did not. "I could not test this part" is useful information; a confident claim that turns out false costs the next person hours. Unverified work is welcome; it just has to be labelled.

Keep a pull request to one concern. If you fixed a bug and noticed three other things, that is four pull requests, or one plus an issue.

Security#

Never commit secrets. .env is gitignored. If you think you committed a credential, say so immediately: the fix is to rotate it, not to hide the commit.
Do not open a public issue for a vulnerability. Contact the maintainer privately first.

See Security for what self-hosting over HTTP costs, and why changes that make the secure path easier are very welcome.

Licensing#

FLICKED is MIT licensed. By contributing, you agree your work is released under the same licence. If you port code from elsewhere, say where it came from and under what licence: FLICKED builds on other people's work and intends to credit it properly.