Skip to main content

Pull Request Process

Overview​

All code changes to BookWish must go through a pull request (PR) process. This ensures code quality, maintainability, and alignment with project standards.

Creating a Pull Request​

Before You Start​

  1. Check the issue tracker - Ensure your work aligns with planned features or bug fixes
  2. Review coding standards - Familiarize yourself with our Code Style Guide
  3. Create a branch - Use a descriptive branch name (e.g., feature/user-wishlist, fix/login-bug)

PR Requirements​

Every pull request must include:

  • Clear title - Describe what the PR does in one line
  • Description - Explain the changes, why they're needed, and how they work
  • Related issues - Link to any related issues or work packs
  • Screenshots - For UI changes, include before/after screenshots
  • Testing notes - Describe how you tested the changes

PR Checklist​

Before submitting, ensure:

  • All tests pass (npm test in backend, flutter test in app)
  • Code follows our Code Style Guide
  • No any types in TypeScript code
  • No console.log or print() statements
  • No TODO comments in production code
  • Linter passes with no errors (npm run lint, flutter analyze)
  • Build succeeds (npm run build, flutter build)
  • Commit messages follow our conventions
  • Documentation is updated if needed

Code Review Process​

Review Timeline​

  • PRs should be reviewed within 24-48 hours
  • Address review comments within 24 hours
  • Re-reviews typically happen within 24 hours

Review Criteria​

Reviewers will check for:

  1. Correctness - Does the code work as intended?
  2. Style compliance - Does it follow our coding standards?
  3. Test coverage - Are there appropriate tests?
  4. Documentation - Is the code well-documented?
  5. Performance - Are there any performance concerns?
  6. Security - Are there any security issues?

Addressing Feedback​

  • Respond to all review comments
  • Make requested changes in new commits (don't force push)
  • Mark conversations as resolved when addressed
  • Request re-review when ready

Merging​

Merge Requirements​

A PR can be merged when:

  • At least one approval from a maintainer
  • All CI checks pass
  • All review comments are resolved
  • No merge conflicts

Merge Strategy​

  • Use Squash and Merge for feature branches
  • Ensure the squashed commit message is clear and follows our commit conventions
  • Delete the branch after merging

Special Cases​

Hotfixes​

For critical production issues:

  1. Create a branch from main (or production branch)
  2. Make the minimal fix
  3. Fast-track review with [HOTFIX] in the PR title
  4. Deploy immediately after merge

Work-in-Progress PRs​

  • Use [WIP] prefix or GitHub's draft PR feature
  • Useful for early feedback
  • Cannot be merged until ready for review

Best Practices​

Keep PRs Small​

  • Aim for PRs under 400 lines of changes
  • Split large features into smaller, reviewable chunks
  • Each PR should have a single, clear purpose

Write Good Descriptions​

## What this PR does

Implements user wishlist feature allowing users to save books they want to read.

## Why

Users requested ability to track books they're interested in without purchasing.

## How to test

1. Log in as a test user
2. Navigate to a book detail page
3. Click "Add to Wishlist"
4. Verify book appears in wishlist page

## Related Issues

Closes #123

Respond to Reviews Gracefully​

  • Thank reviewers for their time
  • Ask questions if feedback is unclear
  • Explain your reasoning if you disagree
  • Be open to suggestions and learning

Tools and Automation​

CI Checks​

All PRs automatically run:

  • Linting (eslint, flutter analyze)
  • Type checking (tsc, dart analyze)
  • Tests (jest, flutter test)
  • Build validation

Branch Protection​

The main branch is protected and requires:

  • Passing CI checks
  • At least one approval
  • Up-to-date with base branch

Getting Help​

If you need help with your PR:

  1. Add a comment explaining where you're stuck
  2. Tag relevant maintainers with @username
  3. Join our development chat (if available)
  4. Check existing PRs for examples

References​