Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (103 loc) · 7.62 KB

CONTRIBUTING.md

File metadata and controls

159 lines (103 loc) · 7.62 KB
Raw

Contributing to Room TBA

Thanks for helping UPLB students find rooms. You do not need to clone this repo unless you are writing code.

Start here: pick the path that fits you.

Path Who What to do Open a PR?
Report wrong data Anyone on campus File a data issue or use in-app suggest No
Campus gate coordinates Data volunteers Fill gate spreadsheet, file batch issue No
Campus QA Testers Verify the app on your phone No
Developers Coders Branch, code, PR to staging Yes
Good first issues New devs Smaller coding tasks Yes
Maintainers / AI agents Core team, Cursor See AGENTS.md Yes

Community: Discord · Messenger (contribute) · UPLB Tools

Report wrong data

Use this when a schedule, pin, direction, or building name is wrong.

  1. In the app: open the room or building → Suggest an edit (if you have contributor access).
  2. On GitHub: New data correction issue.
  3. Chat: Discord or Messenger if GitHub is awkward.

Include:

  • Room or building name (e.g. PSLH 1, PhySci)
  • Term, if it is schedule-related
  • What is wrong and what it should be
  • How you verified (walked there, SAIS, org page, photo)

You do not need to open a pull request. Someone else will ship the fix and reply on the issue.

Approved suggest-edits for campus map entities (buildings, rooms, pins, and similar fields) are licensed CC-BY 4.0. Class schedules imported from AMIS/CRS are not re-licensed that way. Details: Terms — Data licenses.

Campus gate coordinates

Use this when you can verify where campus gates and entry points are on the map. This feeds #157 (gates as searchable entities).

  1. Download data/campus-gate-coordinates-template.csv from this repo (or copy into Google Sheets via File → Import).
  2. Fill one row per gate. Starter rows list common gates from building directions and jeepney routes; leave lat/lon blank until you verify on site (do not copy coordinates from other apps without checking).
  3. For each gate you verify:
    • Stand at the gate sign or main vehicle/pedestrian entry.
    • Record lat and lon (phone GPS or OpenStreetMap pin at the entry).
    • Set gate_type (vehicle, pedestrian, or both), verified to yes, and verification_method (e.g. "walked there 2026-07-16, GPS at sign").
    • Optional: directions (one sentence for walkers), osm_link, notes.
  4. When a batch is ready, open a Gate coordinates (batch) issue. Attach the filled CSV or link your Google Sheet.
  5. A maintainer imports verified rows when the entry_points schema ships (#157).

You do not need to open a pull request.

Column reference: name, short_name, slug, gate_type, lat, lon, is_primary, directions, osm_link, verified, verification_method, notes.

Campus QA

Use this when you can test the live or staging app on a real device.

  1. New campus QA issue
  2. Label qa is applied automatically.

Helpful checks: search a room you know, open schedules for the current term, try offline mode after loading once, check layout at narrow phone width.

No PR required. Describe what you saw. A developer will fix it from your report.

Developers (no AI required)

You can contribute code without using Cursor, agents, or AGENTS.md.

Setup

  1. Install Bun 1.3+
  2. Clone the repo, copy .env.example to .env
  3. Set DATABASE_URL (Supabase Postgres; session pooler recommended for local dev)
  4. Optional: ADMIN_PASSWORD for editor login locally
bun install
bun dev

Open http://localhost:4321. More setup help: docs/developer-guide.md.

Empty database? bun run seed:sample loads a small fictional campus (buildings, rooms, two terms of classes) so the app has something to show — see docs/fork-data-guide.md.

Workflow

  1. Find or file an issue (coding task template or good first issue).
  2. Branch off staging (not main).
  3. Make your change.
  4. Before opening a PR:
  • bun test src
  • bun run lint (or bunx biome format on files you touched)
  • bun run build for substantive changes (needs DATABASE_URL)
  1. Open a PR to staging. Use the PR template checkboxes.
  2. Use Conventional Commits in commit messages (fix(map): …, feat(api): …).

Production: features merge to staging first. Release to production is a separate staging → main PR (maintainers).

What CI does on your PR

If you forked the repo, GitHub will not give your pull request access to our secrets. That is a GitHub security rule, not a judgement about your change.

  • verify (lint, unit tests, component tests, build) runs normally. This is the check to watch.
  • migrations reports a skip notice, because the schema check needs database credentials your fork cannot see.
  • The end-to-end suites do not run. A maintainer runs them from a branch on this repo before merging.

If you have push access here, branch directly on this repo instead of forking and the full stack runs.

Picking up a campus issue

If someone filed a data or qa issue without code:

  1. Comment that you are working on it
  2. Implement the fix
  3. Open a PR to staging and link the issue (Closes #NNN)
  4. Thank the reporter in the issue when merged

Optional (map / editor PRs only)

Maintainers and agents

AGENTS.md is for AI assistants and maintainers who ship quickly across many files. Human developers do not need to read it.

Includes: branch rules, issue hygiene for detailed specs, Cursor workflow skill, map chrome guardrails, agent tooling (Caveman + Ponytail).

One-time agent setup (maintainers): bun run install:agent-tooling then bun run install:agent-plugins — see agent tooling.

Maintainer chat: Discord · Messenger (maintain)

Volunteer triage

Running Discord triage or weekly issue review? See docs/volunteer-triage.md.

Code of conduct

Be helpful to students. Do not commit secrets (.env, passwords). Campus data fixes should be verifiable when possible.