Skip to content

docs: add CONTRIBUTING.md with contributor guidelines#427

Open
tarunsinghofficial wants to merge 3 commits intoOneBusAway:developfrom
tarunsinghofficial:doc/contributing-notes
Open

docs: add CONTRIBUTING.md with contributor guidelines#427
tarunsinghofficial wants to merge 3 commits intoOneBusAway:developfrom
tarunsinghofficial:doc/contributing-notes

Conversation

@tarunsinghofficial
Copy link
Copy Markdown
Collaborator

Added the CONTRIBUTING.md for contributors.

Copy link
Copy Markdown
Member

@aaronbrethorst aaronbrethorst left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Fix the Slack channel references: point to https://opentransitsoftwarefoundation.org/join-our-slack
  2. Update the PR title to follow conventional commit format
  3. Consider the suggestions about tone and README placement

@tarunsinghofficial tarunsinghofficial changed the title Doc/contributing notes docs: add CONTRIBUTING.md with contributor guidelines Mar 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants