Skip to main content
This guide covers the pull request workflow, commit conventions, and review process for Brainbox.

​
Before Submitting a PR

Ensure your changes meet all quality standards before opening a pull request.

​
Pre-submission Checklist

1

Run all quality checks

npm run compile  # Type check all packages
npm run lint     # Lint all code
npm run format   # Format all files
npm run test     # Run all tests
2

Verify commits follow conventions

All commits must use the conventional commit format. Git hooks enforce this automatically.
3

Update documentation

If your changes affect user-facing features or APIs, update the relevant documentation.
4

Test manually

Test your changes in both web and desktop applications when applicable.
CI checks must pass before your PR can be merged. Running checks locally saves time.

​
Commit Conventions

Brainbox uses Conventional Commits enforced by commitlint.

​
Commit Format

<type>: <description>

[optional body]

[optional footer]

​
Commit Types

TypeDescriptionExample
featNew featurefeat: add database export functionality
fixBug fixfix: resolve sync conflict in offline mode
docsDocumentation changesdocs: update API documentation
refactorCode refactoring (no feature change or fix)refactor: simplify node permission checks
testAdding or updating teststest: add unit tests for CRDT merge
choreMaintenance tasks (deps, config, etc.)chore: update dependencies
styleCode style/formatting (not CSS)style: fix linting errors
perfPerformance improvementsperf: optimize query performance
ciCI/CD changesci: add deployment workflow
buildBuild system changesbuild: update Vite config
revertReverting previous commitsrevert: revert feat: add export feature

​
Commit Examples

Simple commit: 
git commit -m "feat: add database export functionality"
Commit with body: 
git commit -m "fix: resolve sync conflict in offline mode

Previously, concurrent edits while offline would create
conflicting states that weren't properly merged when
coming back online. This fix ensures CRDT updates are
properly sequenced during reconnection."
Commit with breaking change: 
git commit -m "feat: redesign sync protocol

BREAKING CHANGE: The sync message format has changed.
Clients must upgrade to the new protocol version."
Use git commit without -m to open your editor for multi-line commit messages.

​
Commit Message Guidelines

  • Use the imperative mood (“add feature” not “added feature”)
  • Keep the first line under 72 characters
  • Capitalize the first letter of the description
  • Don’t end the description with a period
  • Use the body to explain what and why, not how
Good: 
feat: add keyboard shortcuts for node navigation

Users can now use arrow keys to navigate between nodes
and Enter to open a node. This improves accessibility
and power-user efficiency.
Bad: 
Added some shortcuts.

​
Creating a Pull Request

​
PR Title

The PR title should follow the same conventional commit format: 
feat: add database export functionality

​
PR Description

Include a clear description with:
  1. Summary: Brief explanation of the changes
  2. Motivation: Why these changes are needed
  3. Related Issues: Link to relevant issues
  4. Testing: How you tested the changes
  5. Screenshots: For UI changes (if applicable)
Example: 
## Summary

Adds database export functionality allowing users to export
their data in JSON and CSV formats.

## Motivation

Users need the ability to export their data for backup purposes
and migration to other tools.

Fixes #123

## Changes

- Add export service with JSON and CSV formatters
- Create export UI in settings panel
- Add background job for large exports
- Update API with export endpoints

## Testing

- Tested export with small databases (< 100 records)
- Tested export with large databases (> 10,000 records)
- Verified CSV format is valid
- Tested cancellation of in-progress exports

## Screenshots

[Screenshot of export UI]

​
Draft PRs

Use draft PRs for work-in-progress:
  1. Open a draft PR early to get feedback
  2. Mark as “Ready for review” when complete
  3. CI checks still run on draft PRs

​
Review Process

​
Requesting a Review

1

Ensure CI checks pass

All automated checks must pass before requesting review.
2

Request reviewers

Request at least one reviewer familiar with the affected code.
3

Respond to feedback

Address review comments promptly and respectfully.
4

Re-request review after changes

After making requested changes, re-request review from the same reviewers.

​
Review Requirements

  • At least one approval required before merging
  • All CI checks must pass
  • No unresolved conversations
  • Up to date with base branch

​
For Reviewers

When reviewing PRs:
  1. Check functionality: Does it work as intended?
  2. Review tests: Are there adequate tests?
  3. Assess code quality: Is it maintainable and readable?
  4. Verify documentation: Is documentation updated?
  5. Consider edge cases: Are edge cases handled?
  6. Check performance: Any performance concerns?

​
Review Comments

Use clear, constructive feedback: Good: 
Consider extracting this logic into a separate function for reusability:

```typescript
function validateNodePermissions(ctx: Context, nodeId: string) {
  // validation logic
}
This would make testing easier and allow reuse in other mutations. 

**Bad:**

```markdown
This is wrong.

​
Merging

​
Merge Strategy

Brainbox uses squash and merge for most PRs:
  • Combines all commits into a single commit
  • Keeps main branch history clean
  • Preserves full history in the PR

​
Before Merging

Ensure:
  • All CI checks pass
  • At least one approval received
  • All review comments addressed
  • Branch is up to date with main
  • PR title follows conventional commit format

​
After Merging

  1. Delete the feature branch
  2. Close any related issues
  3. Monitor CI for post-merge issues

​
Handling Review Feedback

​
Making Changes

When addressing review comments: 
# Make the requested changes
git add .
git commit -m "refactor: extract validation logic"

# Push to the PR branch
git push

​
Resolving Conversations

After addressing a comment:
  1. Respond to explain your changes
  2. Mark the conversation as resolved (if you agree)
  3. Let the reviewer resolve (if requesting re-review)

​
Common PR Issues

​
Failing CI Checks

Linting errors: 
npm run lint
# Fix reported issues
npm run format
Type errors: 
npm run compile
# Fix TypeScript errors
Test failures: 
npm run test -- --watch
# Debug and fix failing tests

​
Merge Conflicts

Resolve conflicts with the base branch: 
git checkout main
git pull
git checkout your-feature-branch
git merge main
# Resolve conflicts
git add .
git commit -m "chore: resolve merge conflicts"
git push
Prefer merging main into your branch over rebasing to avoid force-pushing.

​
Large PRs

If your PR becomes too large:
  1. Consider splitting into multiple smaller PRs
  2. Create a parent issue tracking the overall feature
  3. Submit PRs incrementally, referencing the parent issue

​
PR Size Guidelines

SizeLines ChangedRecommendation
Small< 200Ideal size, quick to review
Medium200-500Good, may need more review time
Large500-1000Consider splitting if possible
Extra Large> 1000Difficult to review, strongly consider splitting
Smaller PRs get reviewed faster and are less likely to have merge conflicts.

​
Questions?

If you have questions about the PR process:
  • Check existing GitHub Issues
  • Ask in PR comments
  • Review merged PRs for examples

Build docs developers (and LLMs) love

Get started for freeTalk to us