Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
83 lines (55 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

83 lines (55 loc) · 5.04 KB
Raw

Contributing to DevForge

This repo is the club's website and member portal at devforge.club. It's also where milestone 2 of the 10 PR Journey happens: your first real code change, reviewed by a maintainer who wants you to succeed.

Haven't done milestone 1 yet? Sign the workbook first: NST-DEVFORGE/workbook.

1. Pick an issue

  • Browse good first issue. Each one names the file, says what "done" means, and estimates the diff size.
  • Comment /assign on it. A bot assigns you straight away if it's free. That's your go-ahead: no code before it, so two people never fix the same thing.
  • One issue at a time. The bot won't assign you a second one while you have an open issue. Finish it, or comment /unassign to hand it back.
  • If you go quiet on an assigned issue for over a week, a maintainer may unassign you so someone else can pick it up.
  • Found something that isn't listed? Open an issue with the Improvement or Bug report template first.

2. Set up

You need Node 24 and npm.

# fork on GitHub first, then:
git clone https://github.com/<you>/DevForge.git
cd DevForge
git remote add upstream https://github.com/NST-DEVFORGE/DevForge.git
npm install
npm run dev          # http://localhost:3000

No secrets needed. The public pages, the build and the tests all run without any .env file. Pages that need the member portal's database (sign-in, dashboard, admin) show an error locally. That's expected, and none of the good first issues need them.

See .env.example for the full list of environment variables those pages need.

3. Make the change

git checkout main && git pull upstream main
git checkout -b fix/<issue-number>-<short-name>     # e.g. fix/37-navbar-next-image
  • Keep it small: under ~50 lines, and only what the issue asks for. Found something else along the way? Open a new issue for it.
  • Match the code around you: its naming, comment style and Tailwind patterns.

Before you push, run exactly what CI runs:

npm run lint     # ESLint
npm test         # Vitest unit tests (lib/**/*.test.ts)
npm run build    # type-check + production build

4. Open the pull request

  • Title: what changed, e.g. Navbar logo: use next/image.
  • Fill in the PR template. Include Fixes #<issue>, how you tested it, and a screenshot for anything visible.
  • A bot checks this. If the description is empty, has Fixes # with no number, or says nothing about testing, it comments with what's missing and labels the PR needs-description. A PR left that way for 2 days is closed automatically — your branch survives, and reopening it after you fix the description carries on as normal.
  • CI must be green: the Lint, Test and Type-check & build checks. If one fails, open the log, fix it and push again. Don't ask someone else to re-run it.

"Pull request creation failed: must be a collaborator"

You opened the PR between two branches of this repo instead of from your fork. Only maintainers can do that. Go to your fork, click Contribute → Open pull request, and check the bar reads:

base repository: NST-DEVFORGE/DevForge · base: main ← head repository: <you>/DevForge · compare: <your branch>

If you only see branch dropdowns, click compare across forks. Never pick main as the compare side: that's our code, not yours.

5. Review

  • Two members of the governance council are requested as reviewers automatically, and one approval is needed to merge. Reply to every comment: change the code, or explain your reasoning once.
  • Push follow-up commits to the same branch. Don't close the PR and open a new one.
  • When it's merged, log the PR URL on milestone 2 of the workbook and write your reflection within 48 hours.

Writing tests

Tests use Vitest and live next to the code: lib/foo.ts → lib/foo.test.ts. See lib/github-auth.test.ts for the house style. A good test fails when the code is broken, so break the line you're testing on purpose once, and watch the test go red.

Deployments

Only main deploys to devforge.club. CI (Lint, Test, Type-check & build) is what checks your PR — those are the three that have to be green.

You may also see a Vercel check:

  • On a PR that changes pages or components, it builds a preview so a reviewer can look at your change, and a screenshot bot comments with pictures of the pages you touched, on desktop and phone widths. Check them: if your change looks wrong there, it looks wrong in production.
  • On a tests-only, docs-only or script-only PR it is skipped: there's nothing to look at.
  • On a PR from a fork it often shows a red ✗ saying "Authorization required to deploy". Ignore it. We don't build previews from forks, it doesn't block merging, and it isn't something you did wrong.