How we work

Context you should have

This project serves a real community. The directory holds real people's names, photos, employers, and countries, and some members have good reasons to care where that information appears.

There is also no staging environment and no test suite. Every merged change goes to production in front of those members, and nothing automated will catch a mistake for you. That is the reason the conventions below are stricter than a project this size might otherwise justify.

Branches and pull requests

Work on a branch, open a pull request, and let someone else read it before it merges. Direct pushes to the default branch should stop now that more than one person is involved.

Keep changes small enough that a reviewer can hold the whole thing in their head. A pull request that changes a route, a policy, and a build configuration at once is three pull requests.

Commit messages

Write a subject line that says what changed, in the imperative: "Regenerate alumni_id when batch year changes", not "fixed stuff".

If the change is not obvious, use the body to explain why. The most useful commit messages in this repository are the ones that record the reasoning behind a decision, or the mistaken assumption that caused a bug. Someone will read it while trying to understand a behaviour that looks wrong.

Before you open a pull request

bun run build     # must succeed
bun run lint      # should not add new errors

The repository has a number of pre-existing formatting errors, so lint does not currently exit clean. Check that your files are not adding new ones rather than trying to fix the whole repository in an unrelated change.

There is no continuous integration yet. Until there is, these checks are on you.

Reviewing

A review here is a real gate rather than a formality, because nothing downstream will catch a problem. Worth checking specifically:

• Does anything touch the database? If so, see Reviewing database changes.
• Does it add a query? Then a policy must allow it, or it returns nothing in production while appearing to work for an administrator.
• Does it render user-supplied content, especially a URL? Links must be restricted to http and https.
• Does it add user-facing text? Both English and Arabic entries are required.
• Does it lay out anything horizontally? Check it in Arabic, where the layout mirrors.
• Does it add an environment variable? Only VITE_ variables may be build-time, and nothing secret may carry that prefix.

Code conventions

Match the surrounding code. The repository has a consistent style, and consistency is worth more than any individual preference.

Specific conventions that are not obvious:

Never hardcode user-facing strings. Every piece of copy goes in the dictionary with both English and Arabic, and is read through the translation function.

Prefer logical CSS properties. start and end rather than left and right, so Arabic mirrors correctly without a second set of rules.

Do not edit generated files. src/routeTree.gen.ts and the generated Supabase types are rewritten by tooling.

Do not add plugins to the Vite configuration by hand. The framework plugin wires up what is needed, and duplicating a plugin breaks the build in ways that are hard to diagnose.

Load the service-role Supabase client lazily, inside server handlers. A top-level import from a route file would pull it into the client bundle and publish the key.

Adding a dependency

The package manager enforces a delay before newly published packages can be installed, as a supply-chain precaution. If you hit that, do not work around it without discussing it first.

Prefer adding nothing. The application already carries a large UI component library; check whether what you need exists before reaching for a new package.

What is out of scope

The product deliberately does not include messaging between members, automated identity verification, or support for faculties beyond this one. If you have a good idea in one of those areas, raise it as a discussion rather than building it.