Contributing

This is the Scaler Open Source Club's own website, and it is also meant to be a first open-source contribution for club members. If this is your first pull request anywhere, you are the intended audience — say so in the PR and someone will walk you through it.

Setup

git clone https://github.com/<org>/<repo>.git
cd <repo>/web
npm install
npm run dev          # http://localhost:3000
                     # port 3000 is often taken; use `npm run dev -- -p 3001`
                     # and pass SITE_URL=http://localhost:3001 to the checks

No credentials, no database, no .env. If npm run dev needs anything from you beyond those commands, that is a bug — please open an issue.

The files that matter

Almost every contribution is an edit to one file under web/content/. They hold all the site's content as typed arrays, one module per topic, so you do not need to touch a React component to add a person, a project, or an answer.

File	What lives there	Page
site.ts	Links, the page list, the footer's institutional copy	every page
essence.ts	What open source is, career impact, the glossary, member stories	Home
positioning.ts	What a member walks away with, the ICPC comparison, the trade-offs	Home
showcase.ts	Verified upstream contributions, and the headline counts derived from them	Home, Projects
projects.ts	Build-day projects, club repos, upstream contributions	Projects
tracks.ts	The three tracks, and the four steps of a first contribution	Programmes, How to Join
programmes.ts	The seven programmes, tiers, their names and colours, the deadline calendar	Programmes
selections.ts	Who got selected into which programme, and by whom	Hall of Fame
people.ts	Alumni, partner organisations, and the counts that span both rosters	Hall of Fame
team.ts	Officers, leads, shadows — the org chart	Team
mentors.ts	The published mentor bench	Team
events.ts	Internal sessions and external events	Events
how-to-join.ts	What we look for, how the club runs, who it is not for, the FAQ	How to Join
join.ts	The named entry paths, the mentor bench, the join form's options	Join, Onboarding
lookup.ts	Looks one person up by name across the lists above. No content of its own.	—

This used to be a single club.ts. It was split because one file holding every page's content meant every content PR touched it and every one of them conflicted. Each module above owns one topic and is the only place that topic is written down, so two of them can never disagree — see lookup.ts for how a section borrows a fact recorded somewhere else instead of restating it.

Editing the join form's options? join.ts holds the four paths, the two hostels and the programme list — and firestore.rules at the repo root keeps a second copy of those values, because Firestore rules cannot import anything. Change one without the other and every member who picks the new option gets a permission error on save, while the page still renders perfectly. Run npm run rules to check, and see FIREBASE.md.

The signed-in half of the site — /join, /onboarding, /dashboard, /admin — is not content and does not live in web/content/. Nothing there is published on the site; see FIREBASE.md before changing it.

// content/selections.ts
export const SELECTIONS: Selection[] = [
  {
    name: "Full Name",
    programme: "GSOC",              // a key of PROGRAMME_NAME in programmes.ts
    year: "2026",                   // the programme edition, not their year of study
    studyYear: "3rd year",          // optional
    org: "The organisation that selected them", // optional until somebody confirms it
    work: "One specific sentence on what they actually built.", // optional
    photo: "/people/full-name.jpg", // optional
    github: "their-login",          // optional
    url: "https://link-that-proves-it",         // optional
    consented: true,                // REQUIRED — see below
  },
];

Run npm run typecheck. If it passes, the shape is right.

Placeholder content, and why it is there

Several sections render obvious placeholders — "Placeholder One", "Example Foundation" — in development and nothing at all in production. That is deliberate: a card grid cannot be designed or reviewed against an empty array, but a production build must never ship an invented name. The switch is process.env.NODE_ENV, so it is structural rather than a note asking somebody to remember.

When you add real entries, the placeholders disappear on their own — the published*() helpers return real content whenever there is any. Do not delete the scaffolds; the next person redesigning that section needs them.

Two rules that get PRs closed

1. Nobody appears on this site without their own permission

Every person entry carries consented. Anything not explicitly true is filtered out and never rendered.

Do not set consented: true on someone else's behalf because you think they would not mind. These are named students, with photos, shown to an international audience — including people who may not want their name attached to a specific organisation publicly. Ask them, then set the flag.

2. Every factual claim carries a link to a primary source

The site has no testimonials and no placement statistics. External verifiability is the only thing making it credible, and the whole page is built on "you can check this". So:

• A number needs a link to the page that states that number.
• The linked page must state the same number. Citing 1,272 while linking a source that says 1,280 is the exact failure this rule exists to prevent — that one shipped once and had to be corrected.
• If you cannot find a primary source, the claim does not go in. This has already cost two good-sounding lines: an invented "only 9 people per college make ICPC" figure that no rulebook or dataset produces, and "open source is an easier door than ICPC", which is false — GSoC 2025 accepted 1,280 of 15,240 applicants.

A weaker claim you can prove beats a stronger one you cannot.

Writing

Match the voice already there. Concretely:

• Say what happened, not how it felt. "Merged a parser fix into OpenCRE" beats "made an amazing contribution".
• No adjectives describing people. Attach them to work instead.
• Sentence case. No exclamation marks.
• Prefer the specific. "Three terms a year" beats "runs frequently".

Before you open a pull request

npm run typecheck    # must pass
npm run palette      # must pass — categorical colour constraints
npm run build        # must pass
npm run smoke        # needs `npm run dev` in another terminal
npm run qa           # must report 0 issues — same
npm run browsers     # all three engines

npm run qa drives real Chromium across every route × four viewports × both themes — 80 combinations. It checks contrast, tap-target sizes, text size, heading order, alt text, horizontal overflow, and that .tap is never combined with a margin utility. Zero issues is the bar, and it is not negotiable for a site whose audience includes people reading it on a phone on campus wifi.

npm run smoke is the one that catches a dead bundle: it asserts hydration, the Join button's visibility on every route, and that the outline and scroll reveals re-derive after a client-side navigation. Run it before qa, because a page serving no JavaScript passes most of what qa checks.

Both of those run signed out, so on /onboarding and /dashboard they only ever see the "sign in first" card. If you touched sign-in, the profile form, the dashboard or anything under /admin, a green run there means the door is not broken and nothing more — the signed-in half is covered by npm run e2e:auth, which drives the whole flow in a real browser against the Auth and Firestore emulators, and by npm run rules:emulator, which executes firestore.rules as several different people. Both need the emulators running; see FIREBASE.md.

If you changed anything visual, also look at it in both themes. On this project that has caught bugs every single time — including a wordmark rendering at 1.11:1 (black on black) that every automated checker passed, because the checker read the declared token and the element was rendering transparent.

Do not run npm run build while npm run dev is running. They share .next, so the build deletes the chunks the dev server is serving. The page still returns 200 and looks fine, but no JavaScript loads. Recover with rm -rf .next and a restart; node scripts/smoke.mjs confirms.

Pull requests

• One change per PR. A content addition and a layout refactor are two PRs.
• Say what you changed and why. If it is visual, attach a before/after screenshot in both themes.
• Link the issue if there is one.
• Do not commit study/ output, node_modules, .next, or any .env file. All are gitignored already; if something slipped through, that is worth an issue.

Good first issues

Look for the good first issue label. Genuinely useful starting points:

• Add an achiever, a project or a core team member to the right file in web/content/ (with consent + proof).
• Add an FAQ entry for a question you actually had before joining.
• Fix a npm run qa failure on a viewport we have not looked at closely.
• Improve a section's copy to be more specific and less promotional.

Code of conduct

Be straightforward and useful. Review the code, not the person. Nobody here is expected to already know how open source works — that is the entire point of the club.