Skip to content
Plugwerk

Pull Request Process

This page is for contributors to the Plugwerk codebase in plugwerk/plugwerk. It summarises what reviewers expect on a Plugwerk PR. The canonical PR template lives in the main repository.

Before opening a PR

Section titled “Before opening a PR”
  • Tests pass locally (./gradlew build for backend, npm run test:run for frontend)
  • Documentation updated where applicable
  • No secrets or credentials committed
  • Commit messages follow Conventional Commits
  • Every new Liquibase changeSet has an explicit rollback: block (or a documented empty-rollback rationale)
  • CLA signed (first-time contributors)

PR scope

Section titled “PR scope”

One logical change per PR. Reference the closing issue with Closes #N in the PR body. For cross-repo context use plugwerk/plugwerk#N or plugwerk/website#N.

Every PR must have at least one label matching the change type (e.g. enhancement, bug, chore, documentation) and a milestone set. Reviewers will not start work on PRs missing either.

Reviewer expectations

Section titled “Reviewer expectations”

Reviewers check for:

  • Architectural fit — the change aligns with existing patterns
  • Test coverage — new behaviour is covered by tests at the right level (unit, integration, or E2E)
  • License headers — every new Kotlin and TypeScript file carries the correct dual-license header (see Code Style — License headers)
  • API stability — public APIs in plugwerk-spi, plugwerk-api-model, and plugwerk-client-plugin are treated as a contract; breaking changes require explicit discussion in the PR
  • Configuration documentation — new properties are documented in both application.yml (inline YAML comment) and the corresponding @ConfigurationProperties class (KDoc)

AI Agent Disclosure

Section titled “AI Agent Disclosure”

Plugwerk welcomes contributions authored with AI assistance, but every PR must declare its authorship transparently. Pick exactly one of the following options in your PR description (the main repository's PR template provides these as checkboxes):

  • Human-authored — the PR was written by a human without AI agent assistance.
  • AI-authored — the PR was written by an AI agent. Name the agent (e.g. "Claude Code", "GitHub Copilot Workspace", "Cursor").
  • Co-authored (human + AI) — a human directed and reviewed the work, while an AI agent produced part of the code.

For the second and third options, every commit produced with AI assistance must include a Co-Authored-By: trailer naming the agent (see Branches & Commits — AI co-authorship).

This disclosure is a contribution requirement, not a quality signal — AI-assisted PRs are reviewed against the same standards as human-authored ones.

Release PRs

Section titled “Release PRs”

Releasing a new Plugwerk version triggers a coordinated set of changes on this website (OpenAPI sync, version bumps, landing-page banner, release notes, smoke test). Those steps are documented in RELEASE_CHECKLIST.md in the website repository.

Release PRs in the main plugwerk/plugwerk repository follow the standard process described above. The checklist applies only to the website-side updates that follow a main-repo release.