Skip to main content

Open Source Contribution Practice

Contributing effectively to an open-source project like Flow Research requires more than technical skill. The human side — reading unfamiliar code, writing reviewable PRs, communicating asynchronously — is what separates reliable contributors from occasional ones.

  • Start with the README and contributor guide.
  • Run the project locally and trace a simple end-to-end flow.
  • Read recent PRs to understand review culture and patterns.
  • Use the issue tracker to find areas with active discussion.

Writing reviewable PRs​

  • Keep changes focused — one concern per PR.
  • Write a clear description explaining what and why, linking to the related issue or design doc.
  • Add tests and update documentation in the same PR.
  • Respond to review feedback promptly and with specific changes or reasoning.

Async communication​

  • Default to writing things down. If it is not documented, it did not happen.
  • Use PR descriptions, issues, and design docs as the source of truth.
  • When blocked, state what you tried, what happened, and what you need.
  • Respect time zones — prefer async over synchronous unless urgency requires otherwise.

Design reviews​

  • Review the design doc before the code. Catch problems early.
  • Leave constructive feedback: state what works, what is unclear, and what concerns you have.
  • Separate nitpicks from blocking issues clearly.

Exercises​

  1. Pick an unfamiliar repository, read the contributor guide, and submit one small improvement (docs fix, test addition, or bug fix).
  2. Write a PR description for a hypothetical change and have a peer review the description itself.
  3. Review three open PRs in the Flow Research repositories and leave one piece of actionable feedback each.