From 376697eeeae1207e48acb73505e0417e0d585965 Mon Sep 17 00:00:00 2001 From: Puneet Dixit <236133619+puneetdixit200@users.noreply.github.com> Date: Wed, 20 May 2026 13:07:55 +0530 Subject: [PATCH] docs: add contributor onboarding guide --- CONTRIBUTING.md | 5 ++ CONTRIBUTOR_ONBOARDING.md | 119 ++++++++++++++++++++++++++++++++++++++ README.md | 4 ++ 3 files changed, 128 insertions(+) create mode 100644 CONTRIBUTOR_ONBOARDING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92c119d..4c4dc75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,11 @@ We work in public. If you can read this, you can help. +New here? Start with the +[contributor onboarding guide](CONTRIBUTOR_ONBOARDING.md) for how to claim work, +which setup to use for each work area, communication norms, ownership, and Slack +welcome templates. + ## How we work **Issues** = "this needs to happen." If you can scope it, you can claim it. diff --git a/CONTRIBUTOR_ONBOARDING.md b/CONTRIBUTOR_ONBOARDING.md new file mode 100644 index 0000000..0d9b25e --- /dev/null +++ b/CONTRIBUTOR_ONBOARDING.md @@ -0,0 +1,119 @@ +# Contributor onboarding + +Welcome to Opportunity Hack. This repo is the public operating board for work that +helps nonprofits, mentors, judges, sponsors, and hackathon volunteers ship more +reliably. + +## Start here + +1. Read the [README](README.md) for the current roadmap. +2. Read [CONTRIBUTING.md](CONTRIBUTING.md) for how issues, PRs, and reviews work. +3. Join [Slack](https://slack.ohack.dev) and say hello in `#contributors`. +4. Pick a small issue labeled [`good-first-task`](../../issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-task). +5. Comment with "I'd like to take this" and a 1-2 sentence plan. + +Wait for a maintainer to assign the issue before doing a large amount of work. If +you are only fixing a typo or clarifying a document, it is fine to open a small PR +and explain the change. + +## How to claim work + +Use this comment format when claiming an issue: + +```text +I'd like to take this. + +Plan: +- What I will change +- How I will verify it +- Any question or dependency I need answered first +``` + +If the issue is labeled `help-wanted`, start with a design comment instead of a +PR. Those issues are usually larger or less defined. + +## Development environments + +Most work in this repo falls into one of these areas: + +| Area | Typical work | Local setup | +| --- | --- | --- | +| Ops docs | README, contributor docs, issue bodies, sponsor/community plans | Any editor plus Git | +| Bootstrap scripts | `scripts/setup.sh`, labels, milestones, issue creation | `gh`, `jq`, Bash | +| Product planning | PRDs, SRDs, UX flows, product decisions | Markdown and GitHub Issues | +| Website or app work | Future Next.js, FastAPI, Postgres, Cloudflare work | Follow the linked repo setup | + +For this repo, validate shell changes with: + +```bash +bash -n scripts/setup.sh +``` + +For documentation-only changes, run: + +```bash +git diff --check +``` + +When a task points to another codebase, follow that repository's setup and test +instructions instead of guessing from this ops repo. + +## Communication norms + +- Keep planning and decisions in public GitHub issues or discussions. +- Use Slack for quick questions, pairing, and finding the right owner. +- Ask early when you are blocked for more than a day. +- Prefer small PRs that reviewers can understand in one sitting. +- If you use AI tools, make sure you understand and can explain the work. + +## Who owns what + +| Area | First place to ask | +| --- | --- | +| Contributor pipeline, Slack, and community rituals | `#contributors` | +| Hackathon mentors, judges, and event operations | Relevant GitHub issue, then Slack | +| Product planning and technical architecture | Issue discussion before PR | +| Sponsorship, nonprofit intake, and outreach | Issue owner or maintainer tagged on the task | +| Repo labels, milestones, setup scripts, and project board | Maintainers in this repo | + +If you do not know the owner, ask in `#contributors` with a link to the issue. + +## Welcome message template + +```text +Welcome to Opportunity Hack, ! + +Glad to have you here. A good first path is: +1. Read https://github.com/opportunity-hack/ops/blob/main/CONTRIBUTOR_ONBOARDING.md +2. Pick a good-first-task issue +3. Comment with your plan before you start + +If you share your background or what kind of work you want to do, we can point you +to an issue that fits. +``` + +## Suggested Slack pinned posts + +Pin these in `#contributors`: + +```text +Start here: +https://github.com/opportunity-hack/ops/blob/main/CONTRIBUTOR_ONBOARDING.md +``` + +```text +Good first tasks: +https://github.com/opportunity-hack/ops/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-task +``` + +```text +How to claim work: +Comment on the issue with "I'd like to take this" plus a 1-2 sentence plan. +Wait for assignment before doing large work. +``` + +```text +Office hours: +Post questions here any time. If you are blocked for more than a day, ask for help +with a link to the issue or PR. +``` diff --git a/README.md b/README.md index 9042439..718900f 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ See the [project board](../../projects) for everything. Comment on an issue to claim it. We'll respond within a few days. +New contributors can follow the one-page +[contributor onboarding guide](./CONTRIBUTOR_ONBOARDING.md) for how to claim work, +set up for different task areas, and ask for help. + ## Roadmap The short version of where we're headed: