Pull Request Workflow

This document outlines the complete pull request process for Openwork, from initial submission to final merge.

Pull Request Process

1. Before Creating a PR

Prerequisites:

  • Ensure your code builds without errors (pnpm build)
  • Pass all TypeScript checks (pnpm typecheck)
  • Run linting (pnpm lint)
  • Update relevant documentation if needed
  • Write tests for new functionality or bug fixes

Branch Requirements:

  • Use descriptive branch names following the format:
    • feature/feature-name for new features
    • fix/issue-description for bug fixes
    • docs/documentation-change for documentation updates
    • refactor/refactoring-name for code improvements

2. Creating the Pull Request

PR Title Format:

  • Use [type]: [description] format
  • Examples:
    • feat: add dark mode support
    • fix: resolve crash on startup
    • docs: update README with new instructions
    • refactor: simplify task queue logic
    • test: add unit tests for authentication

PR Description Template:

## Summary
Brief description of the changes

## Changes Made
- [ ] List of changes
- [ ] Specific features added
- [ ] Bug fixes implemented

## Testing
- [ ] Manual testing completed
- [ ] Automated tests written/updated
- [ ] E2E tests run if applicable

## Related Issues
Closes #[issue-number] if applicable

## Screenshots (if applicable)
Add screenshots to demonstrate the changes

3. Review Criteria

Code Quality

  • TypeScript types are correct and complete
  • Code follows existing patterns and conventions
  • Functions are focused and have single responsibilities
  • Error handling is comprehensive and consistent
  • Code is well-structured and readable

Functionality

  • Feature works as intended
  • No regressions in existing functionality
  • Edge cases are handled appropriately
  • Performance impact is minimal or justified
  • Accessibility requirements are met

Testing

  • All tests pass
  • New functionality has test coverage
  • E2E tests are included for UI changes
  • Test coverage maintained or improved

Documentation

  • Code is properly documented
  • README or other docs updated if needed
  • API changes documented
  • Breaking changes clearly documented

Security

  • No security vulnerabilities introduced
  • Sensitive data handled properly
  • Input validation is in place
  • Dependencies are up-to-date and secure

4. Review Process

Initial Review (1-2 business days)

  • Automatic checks pass (CI, linting, type checking)
  • PR title and description are clear and complete
  • Branch follows naming conventions
  • Basic code review for obvious issues

Detailed Review (3-5 business days)

  • Comprehensive code review
  • Testing verification
  • Documentation review
  • Performance and security considerations

Request Changes

  • Reviewers will provide specific feedback
  • Address all comments and update your PR
  • Reply to each comment when addressing it
  • Push changes to the same branch (no force pushes)

Approval and Merge

  • All review comments addressed
  • CI checks pass
  • At least one maintainer approval
  • No merge conflicts

5. After Merge

Branch Cleanup

  • PR will be automatically closed
  • Branch will be automatically deleted
  • Committers will be added to contributors list

Release Process

  • Features will be included in the next release
  • Bug fixes may be backported to stable versions
  • Release notes will be updated with changes

6. Common Scenarios

Multiple Rounds of Reviews

  • Don’t be discouraged by multiple review rounds
  • Each round improves code quality
  • Address comments systematically
  • Thank reviewers for their time

Large Changes

  • Break into smaller, logical PRs
  • Create draft PRs early for feedback
  • Consider feature branches for long-lived changes
  • Document design decisions clearly

Bug Fixes

  • Include test case that reproduces the bug
  • Add test that verifies the fix
  • Consider edge cases similar to the original bug

Documentation Updates

  • Keep examples up-to-date
  • Ensure links work and are relevant
  • Update both code comments and user-facing docs

Best Practices

Communication

  • Be responsive: Address review comments within 48 hours
  • Be respectful: Thank reviewers for their feedback
  • Be clear: Explain your reasoning when it’s not obvious
  • Be collaborative: View reviews as opportunities to improve

Code Quality

  • Keep PRs focused: Address one concern per PR when possible
  • Write self-documenting code: Clear names and structure over comments
  • Handle errors gracefully: Provide meaningful error messages
  • Consider performance: Profile changes when applicable

Testing

  • Test your changes: Verify both positive and negative cases
  • Add regression tests: Prevent future issues
  • Update E2E tests: For UI or integration changes
  • Consider edge cases: What could go wrong?

Documentation

  • Update README: For new features or breaking changes
  • Add code comments: For complex logic or important decisions
  • Update API documentation: For public API changes
  • Link to related issues: Help reviewers understand context

Troubleshooting

CI Failures

  • Check the CI logs for specific errors
  • Fix linting and type check errors locally
  • Ensure all tests pass before pushing
  • Use pnpm clean if build issues persist

Merge Conflicts

  • Pull the latest changes before resolving conflicts
  • Resolve conflicts carefully and test
  • Update your PR description with conflict resolution details

Review Delays

  • Be patient with review timelines
  • Consider adding draft PRs for early feedback
  • Re-ping if review is needed after 5+ business days

Conclusion

Following this workflow helps maintain code quality and ensures smooth collaboration. Remember that code reviews are collaborative - they’re meant to improve the code together, not criticize individual contributions.

Thank you for your contributions to Openwork!

Back to top

OpenWork Documentation - Community documentation for accomplish-ai/openwork