Skip to main content

Pull Request Guidelines

How to submit effective pull requests to Wellpipe.

Before You Start​

  1. Check existing issues - Is someone already working on this?
  2. Open an issue first - For significant changes, discuss before coding
  3. Review the codebase - Understand existing patterns

Creating a PR​

Title​

Follow commit message conventions:

feat: add Oura provider integration
fix: handle rate limit errors gracefully
docs: improve authentication guide

Description Template​

## Summary

Brief description of what this PR does.

## Changes

- Added X
- Fixed Y
- Removed Z

## Testing

How did you test these changes?

## Related Issues

Fixes #123

Keep PRs Focused​

One logical change per PR:

✅ Good: "Add Oura sleep API integration"
❌ Bad: "Add Oura provider, refactor token handling, update docs"

Split large changes into multiple PRs.

Code Requirements​

Tests​

  • Add tests for new functionality
  • Update tests for changed behavior
  • All tests must pass
npm test

Type Checking​

npm run typecheck

Linting​

npm run lint

Documentation​

  • Update relevant docs for user-facing changes
  • Add JSDoc for new public APIs

Review Process​

1. Automated Checks​

When you open a PR:

  • CI runs tests, linting, type checking
  • All checks must pass before review

2. Maintainer Review​

A maintainer will review for:

  • Code quality and style
  • Architectural fit
  • Test coverage
  • Documentation

3. Feedback​

We may request changes. This is normal and collaborative.

When addressing feedback:

  • Push new commits (don't force-push during review)
  • Reply to each comment
  • Re-request review when ready

4. Approval and Merge​

Once approved:

  • We'll merge your PR
  • Your commits may be squashed
  • You'll be credited in the release notes

Timeline​

  • Initial review: 1-3 days
  • Follow-up reviews: 1-2 days
  • Complex PRs may take longer

If you haven't heard back in a week, feel free to ping.

Tips for Faster Reviews​

Small PRs​

< 400 lines of changes ideally. Large PRs are harder to review.

Clear Description​

Help reviewers understand your changes:

  • What problem does this solve?
  • Why this approach?
  • Any trade-offs?

Self-Review First​

Before submitting:

  • Review your own diff
  • Check for debug code, console.logs
  • Ensure tests pass locally

Respond Promptly​

Quick responses keep the review moving.

After Merge​

  • Delete your branch
  • Close related issues (if not auto-closed)
  • Celebrate your contribution!

Stale PRs​

PRs without activity for 30 days may be closed. Feel free to reopen if you want to continue.

Getting Help​

  • Ask questions in the PR comments
  • Tag maintainers if stuck
  • Join discussions in issues