docs: add CONTRIBUTING.md with contributor guidelines#427
docs: add CONTRIBUTING.md with contributor guidelines#427tarunsinghofficial wants to merge 3 commits intoOneBusAway:developfrom
Conversation
7866a19 to
ef37853
Compare
aaronbrethorst
left a comment
There was a problem hiding this comment.
Tarun — good initiative putting together a contributing guide. The writing is clear and the tone hits the right balance between welcoming and direct. I have a few things that should be tightened up before merging.
Critical Issues (0 found)
None.
Important Issues (2 found)
1. References to "Slack channel" with no link or context
File: CONTRIBUTING.md:7, 35
The doc mentions "the project's Slack channel" twice but doesn't link to it or explain how to join. A contributor reading this has no way to find it. Either add a link (e.g., to the OneBusAway Slack workspace signup page) or remove the Slack references. The README doesn't mention Slack either, so there's no breadcrumb trail for someone to follow.
2. PR title doesn't follow project conventions
The PR title Doc/contributing notes doesn't follow the conventional commit format used by this project (e.g., docs: add CONTRIBUTING.md). This matters because the title becomes the merge commit message. Please update it to something like:
docs: add CONTRIBUTING.md with contributor guidelines
Suggestions (2 found)
1. "Don't open a PR for an issue nobody has assigned to you" may be too strict
File: CONTRIBUTING.md:11
Please don't open a PR for an issue nobody has assigned to you.
This is a reasonable policy, but combined with "hold off on opening a branch" on line 15, it could discourage eager contributors. Consider softening to something like: "If you'd like to work on an issue, comment on it first so a maintainer can assign it to you — this avoids duplicate effort." That communicates the same intent without sounding like a gate.
2. Contributing section placement in README
File: README.md
The Contributing section is added between the setup instructions and the .env file keys section. Consider placing it at the bottom of the README instead — contributors will naturally scroll down after reading setup instructions, and it keeps the technical reference material (env vars) closer to the setup section where developers look for it.
Strengths
- Well-written, conversational tone that feels genuinely welcoming
- The AI-Generated Code section is excellent — clear expectations without being preachy
- Good coverage of the full contributor workflow: finding issues → claiming → coding → PR → review
- Code Style section correctly references the project's tooling (Prettier, ESLint) and Svelte 5 runes
Recommended Action
- Fix the Slack channel references: point to https://opentransitsoftwarefoundation.org/join-our-slack
- Update the PR title to follow conventional commit format
- Consider the suggestions about tone and README placement
Added the CONTRIBUTING.md for contributors.