Pull Requests

Guide to submitting pull requests to WP Kernel.

📖 For release workflow and versioning, see RELEASING.md in project root (canonical source).

Before You Start

Read the Contributing Guide
Check existing issues for related work
Discuss large changes in an issue first
Review RELEASING.md in project root for sprint-driven re2. Maintainer reviews PR changes.

Maintainer merges PR to main.
Maintainer prepares release by updating versions and tagging.
Maintainer publishes to npm manually.

Questions?

Documentation: https://theGeekist.github.io/wp-kernel/
Issues: https://github.com/theGeekist/wp-kernel/issues
Discussions: https://github.com/theGeekist/wp-kernel/discussions

Quick Reference

bash

# Before starting
git checkout -b feature/my-feature

# While working
pnpm test
pnpm lint

# Update CHANGELOG.md in affected packages

# Before pushing
git add .
git commit -m "feat: my feature"
git push origin feature/my-feature
```e workflow

## Creating a Pull Request

### 1. Fork & Branch

```bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/wp-kernel.git
cd wp-kernel

# Add upstream remote
git remote add upstream https://github.com/theGeekist/wp-kernel.git

# Create a feature branch
git checkout -b feature/my-feature

2. Make Changes

Follow Coding Standards:

bash

# Make your changes
# ...

# Run tests
pnpm test
pnpm e2e

# Run lint
pnpm lint

# Run typecheck
pnpm typecheck

3. Update CHANGELOG

For Sprint PRs, update CHANGELOG.md files in affected packages:

markdown

## 0.x.0 [Unreleased]

### Added

- Sprint 5: Bindings & Interactivity (Block Bindings, Interactivity API, Providers)

### Fixed

- Bug fix description

Direct commits to main (infra/docs only) do not trigger releases.

See RELEASING.md in project root for the canonical sprint PR workflow and versioning guidelines.

4. Commit Changes

Use Conventional Commits:

bash

git add .
git commit -m "feat(resources): add custom cache invalidation"

5. Push & Open PR

bash

git push origin feature/my-feature

Then open a PR on GitHub using the PR template (.github/PULL_REQUEST_TEMPLATE.md).

✗ Never create ad-hoc PRs without the template!

PR Template

Always use .github/PULL_REQUEST_TEMPLATE.md when creating PRs. The template includes:

Sprint/scope identification
Roadmap and sprint doc links (please include)
Release type selection (minor/patch/major)
CHANGELOG.md confirmation checklist
Testing and verification steps

Required Sections

Sprint Metadata – Sprint number, type (feature/alignment/norms)
Scope – Brief description of changes
Context – Links to roadmap, sprint doc, and related PRs/issues
Testing – How to test the changes
Release – Bump type and CHANGELOG confirmation

See RELEASING.md in project root for the canonical sprint PR workflow.

PR Requirements

Must Have

[ ] All tests pass – Unit and E2E tests must be green.
[ ] Lint passes – Zero ESLint errors.
[ ] CHANGELOG.md updated – Unless docs-only change.
[ ] Conventional commits – Proper commit message format.
[ ] Description – Clear what/why/how.

Should Have

[ ] Tests for new code – Unit tests for new functionality.
[ ] E2E tests – For user-facing features.
[ ] Documentation – Update docs for API changes.
[ ] Examples – Update examples if relevant.

Nice to Have

[ ] Performance tests – For performance-critical code.
[ ] Screenshots – For UI changes.
[ ] Migration guide – For breaking changes.

Review Process

CI Checks

All PRs must pass CI:

✓ Lint
✓ TypeScript
✓ Build
✓ Unit Tests
✓ E2E Tests

Code Review

Automated review – CI checks run automatically.
Maintainer review – One approval required.
Changes requested – Address feedback and push updates.
Approved – PR is ready to merge.

Merge Strategy

Squash merge – All PRs are squashed into one commit.
Commit message – Should follow Conventional Commits.
Branch deletion – Feature branch is deleted after merge.

Common Scenarios

Addressing Review Feedback

bash

# Make changes based on feedback
# ...

# Commit
git add .
git commit -m "refactor: address review feedback"

# Push
git push origin feature/my-feature

CI will re-run automatically.

Updating from Main

bash

# Fetch latest
git fetch upstream

# Merge main into your branch
git checkout feature/my-feature
git merge upstream/main

# Resolve conflicts if any
# ...

# Push
git push origin feature/my-feature

Amending Commits

bash

# Make additional changes
# ...

# Amend previous commit
git add .
git commit --amend --no-edit

# Force push (only on your fork!)
git push origin feature/my-feature --force-with-lease

Updating Changeset

bash

```bash
# Update CHANGELOG.md in affected packages
# Add/modify entries under ## 0.x.0 [Unreleased]

# Commit
git add packages/*/CHANGELOG.md
git commit -m "chore: update changelog"
git push

PR Types

Bug Fix

markdown

## What

Fix validation error for empty description field.


## PR Types

### Bug Fix

```markdown
## What

Fix validation error for empty description field.

## Why

Users were unable to submit things without descriptions, even though description is optional.

Fixes #123

## How

Updated validation schema to allow empty strings for description field.

## Testing

1. Navigate to Things page
2. Click "Add New"
3. Enter title only, leave description empty
4. Click "Create"
5. Thing should be created successfully

New Feature

markdown

## What

Add custom cache invalidation strategies for Resources.

## Why

Some resources need fine-grained control over when cache is invalidated based on the specific action and payload.

## How

Added optional `shouldInvalidate` function to resource config that receives action and payload and returns boolean.

## Testing

See new unit tests in `packages/core/src/__tests__/resource.test.ts`.

## Breaking Changes

None. This is an optional enhancement.

Documentation

markdown

## What

Document block bindings usage patterns.

## Why

Users were asking how to implement server-side bindings for SEO.

## How

Added comprehensive guide with examples in `/docs/guide/block-bindings.md`.

## Testing

Review documentation locally:

1. `pnpm docs:dev`
2. Navigate to Guide → Block Bindings
3. Verify examples are clear

Refactor

markdown

## What

Extract transport retry logic into separate utility.

## Why

Retry logic was duplicated across resource methods. Extracting improves maintainability.

## How

Created `packages/core/src/transport/retry.ts` with exponential backoff implementation. Updated all resource methods to use it.

## Testing

All existing tests pass. Added unit tests for retry utility.

## Breaking Changes

None. Internal refactor only.

Troubleshooting PRs

CI Failing

Lint Errors

bash

# Check locally
pnpm lint

# Auto-fix
pnpm lint:fix

# Commit and push
git add .
git commit -m "style: fix lint errors"
git push

Test Failures

bash

# Run locally
pnpm test
pnpm e2e

# Debug
pnpm test --watch
pnpm e2e --headed

# Fix and push

Build Errors

bash

# Clean build
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build

Merge Conflicts

bash

# Fetch latest
git fetch upstream

# Rebase on main
git rebase upstream/main

# Resolve conflicts
# Edit conflicting files
git add .
git rebase --continue

# Force push
git push origin feature/my-feature --force-with-lease

Changeset Missing

bash

### CHANGELOG Missing

```bash
# Update CHANGELOG.md in affected packages
# Add entries under ## 0.x.0 [Unreleased]

# Commit
git add packages/*/CHANGELOG.md
git commit -m "chore: update changelog"


## After Merge

### Clean Up Branches

```bash
# Delete local branch
git checkout main
git branch -d feature/my-feature

# Delete remote branch (if not auto-deleted)
git push origin --delete feature/my-feature

Update Local Main

bash

# Fetch and pull latest
git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Release Process

Releases are automated:

Maintainer merges PRs with changesets.
Changesets bot opens "Version Packages" PR.
Maintainer reviews version changes and changelog.
Maintainer merges version PR.
GitHub Actions publishes to npm automatically.

Questions?

Documentation: https://theGeekist.github.io/wp-kernel/
Issues: https://github.com/theGeekist/wp-kernel/issues
Discussions: https://github.com/theGeekist/wp-kernel/discussions

Quick Reference

bash

# Before starting
git checkout -b feature/my-feature

# While working
pnpm test
pnpm lint
pnpm cs:new:minor "Sprint X: Description"

# Before pushing
git add .
git commit -m "feat: my feature"
git push origin feature/my-feature

# After PR merged
git checkout main
git pull upstream main
git branch -d feature/my-feature

Thank you for contributing! 🎉

Pull Requests ​

Before You Start ​

Questions? ​

Quick Reference ​

2. Make Changes ​

3. Update CHANGELOG ​

4. Commit Changes ​

5. Push & Open PR ​

PR Template ​

Required Sections ​

PR Requirements ​

Must Have ​

Should Have ​

Nice to Have ​

Review Process ​

CI Checks ​

Code Review ​

Merge Strategy ​

Common Scenarios ​

Addressing Review Feedback ​

Updating from Main ​

Amending Commits ​

Updating Changeset ​

PR Types ​

Bug Fix ​

New Feature ​

Documentation ​

Refactor ​

Troubleshooting PRs ​

CI Failing ​

Lint Errors ​

Test Failures ​

Build Errors ​

Merge Conflicts ​

Changeset Missing ​

Update Local Main ​

Release Process ​

Questions? ​

Quick Reference ​

Pull Requests

Before You Start

Questions?

Quick Reference

2. Make Changes

3. Update CHANGELOG

4. Commit Changes

5. Push & Open PR

PR Template

Required Sections

PR Requirements

Must Have

Should Have

Nice to Have

Review Process

CI Checks

Code Review

Merge Strategy

Common Scenarios

Addressing Review Feedback

Updating from Main

Amending Commits

Updating Changeset

PR Types

Bug Fix

New Feature

Documentation

Refactor

Troubleshooting PRs

CI Failing

Lint Errors

Test Failures

Build Errors

Merge Conflicts

Changeset Missing

Update Local Main

Release Process

Questions?

Quick Reference