Skip to content

pull-requests.instructions.md

Latest commit

 

History

History
241 lines (179 loc) · 11.5 KB

pull-requests.instructions.md

File metadata and controls

241 lines (179 loc) · 11.5 KB
file_type instructions
title Pull Request Creation Instructions
description Canonical instructions for creating, labeling, and submitting Pull Requests in LightSpeedWP projects. Reference for templates, automation, and labeling strategy.
scope organization-wide
version 1.3
last_updated 2026-06-03
owners
lightspeedwp/maintainers
tags
pull requests
templates
frontmatter
automation
labels
branching
checklists

LightSpeedWP Pull Request (PR) Creation Instructions

You are a pull request quality partner. Follow our PR templates, branching, and labelling standards to open review-ready pull requests. Avoid YAML PR forms, missing required labels, or branches that break naming rules.

Overview

Applies to all PR templates and submissions. Covers frontmatter, branching, templates, labelling, automation, and lifecycle expectations. Excludes issue creation (see issues.instructions.md).

General Rules

  • Use Markdown PR templates with required frontmatter; avoid YAML forms.
  • Follow branch naming patterns and ensure one-hot label families (status:*, priority:*, release:*, type:*).
  • Complete all template fields, checklists, and changelog sections.
  • Keep PRs automation-ready; monitor CI and respond to reviews promptly.
  • Maximise metadata completeness on every PR update. Populate all applicable metadata fields: labels, PR type, project fields, milestone, assignees, projects, linked issues, and dependency relationships.

Detailed Guidance

  • Follow the numbered sections below for templates, frontmatter, branch naming, opening steps, labelling, and review lifecycle.
  • Align with labeler rules and release automation guidance.

Examples

  • Good: feat/feature-name branch using Feature template with required labels, linked issues, and completed checklist.
  • Avoid: PRs from improperly named branches, missing labels, or empty template sections.

Validation

  • Ensure PR uses correct template with complete frontmatter.
  • Verify labels meet required families and branch naming matches patterns.
  • Confirm CI (lint/test/build) passes and checklists are completed.

This document defines the standards, steps, and requirements for opening, labeling, and maintaining Pull Requests (PRs) in LightSpeedWP repositories. All contributors, bots, and maintainers must follow these instructions to ensure automation, traceability, and high-quality code review.

1. Use Markdown PR Templates with YAML Frontmatter

  • All PR templates are Markdown (.md) files with a YAML frontmatter block, stored in:
    • .github/PULL_REQUEST_TEMPLATE.md (general/default)
    • .github/PULL_REQUEST_TEMPLATE/*.md (specific templates: feature, bugfix, chore, docs, release, etc.)
  • Do NOT use YAML form PR templates. All automation and labeling requires Markdown-based templates.

See PR Creation Process for specifications.

2. Required PR Frontmatter Fields

Each PR template must begin with a YAML frontmatter block, for example:

---
name: "Feature PR"
about: "New features or enhancements"
title: "feat: {short summary}"
labels: ["type:feature", "status:needs-review", "area:feature"]
---

Required fields:

  • name: Short label for the template selector.
  • about: Short description of template purpose.
  • title: Default PR title (use {short summary} or similar).
  • labels: Array of default labels for new PRs.

Optional fields:

  • assignees: Default assignees.
  • projects: Default project boards.

See frontmatter instructions and frontmatter schema for validation.

3. Branch Naming Requirements

  • Follow the canonical branch naming pattern: {type}/{scope}-{short-title}
    • Examples: feat/block-editor-colors, fix/theme-json-colors, docs/readme-update
  • Allowed prefixes map directly to PR type and automation:
    • feat/, fix/, hotfix/, release/, refactor/, chore/, docs/, test/, perf/, ci/, build/, deps/, design/, a11y/, ux/, i18n/, ops/, and more (see BRANCHING_STRATEGY.md).
  • PRs from incorrectly named branches may be blocked by CI.

See BRANCHING_STRATEGY.md for full details and enforcement regex.

4. How to Open a Pull Request

Step-by-Step

  1. Update your branch (rebase/merge latest main or develop).

  2. Choose the correct PR template when opening your PR. Templates are:

    • Bugfix, Feature, Chore, Docs, Build/CI, Refactor, Hotfix, Release, General, etc.
    • For template details, see .github/PULL_REQUEST_TEMPLATE/*.md and PR Creation Process.

  3. Fill out all required fields in the template:

    • Linked issues: Use Closes #123 or similar.
    • Description: Clearly state what changed and why.
    • Changelog section: [Required for release automation.]
    • Checklist: Complete all items, including explicit accessibility and security checks.

  4. Write a clear title Format: [Type] Area/Component: Brief summary (Closes #issue) Example: [Feature] Block Patterns: Add new testimonial pattern (Closes #201)

  5. Review and confirm labels

    • Labels are auto-applied via frontmatter and .github/labeler.yml based on branch prefix and file paths.
    • Minimum required labels:
      • One status:* (e.g. status:needs-review)
      • One type:* (e.g. type:feature, type:bug, etc.)
      • One priority:* (e.g. priority:normal)
      • At least one area:* or comp:* if possible
      • One release:* (e.g. release:patch, release:minor, release:major)

  1. Assign milestones/projects if applicable.

  2. Open the PR and monitor CI, review, and status checks.

5. Labeling & Automation

  • Labeler automation:

    • .github/labeler.yml maps branch prefixes and file globs to labels.
    • Branch prefix sets type:* and status:needs-review.
    • File paths set area:*, comp:*, lang:*, etc.

  • Workflows enforce:

    • Only one status:*, one priority:*, one release:* at a time
    • Changelog label (meta:needs-changelog) is added if missing
    • PRs missing required labels cannot be merged; see missing-labels.md

  • Release automation:

Metadata Completeness Default

  • Treat metadata completeness as mandatory, not optional, during PR triage and updates.
  • Always set or verify one-hot label families (status:*, priority:*, type:*, release:*) and relevant area:* or comp:* labels.
  • Always set or verify milestone when the PR targets a release train or milestone bucket.
  • Always set or verify project fields (for example Status, Priority, Type) when the PR is on a project board.
  • Always set or verify relationships where applicable:
    • Linked issues using closing keywords (Closes #123) when true
    • Dependencies (blocked by, depends on) in PR body or linked issue graph
    • Parent feature or epic issue references
  • If a metadata value cannot be inferred safely, leave it unchanged and record a short follow-up note describing what is missing.

6. PR Review & Lifecycle

  • Checklist must be completed (tests, docs, linked issues, CI, and explicit accessibility/security checks).
  • Accessibility baseline: Confirm semantic structure, keyboard/focus behaviour, and contrast/non-colour cues against WCAG 2.1 AA or higher.
  • Security baseline: Confirm validation/sanitisation, context-specific escaping, nonce/capability checks where relevant, and OWASP risk review.
  • CI and all status checks must pass.
  • Respond promptly to reviewer feedback; see awaiting-author.md
  • Ready for review: Mark as ready and ping reviewers; see ready-for-review.md
  • Draft PRs: Use draft status for early feedback; see draft-pr.md
  • Merge discipline: Use squash & merge, delete branch, resolve all conversations; see merge-discipline.md

7. Reference Files and Checklists

8. Tips for Excellent PRs

  • Link all related issues with closing keywords.
  • Add screenshots or recordings for UI/visual changes.
  • Keep PRs focused and small; split large changes.
  • Use clear, actionable commit messages.
  • Update documentation when behavior changes.
  • Use the correct template for your change type.
  • Double-check all checklists before marking ready for review.
  • Always follow org-wide Coding Standards.

9. Common Saved Replies & Guidance

For maintainers and reviewers, reference these Saved Replies for standard feedback:

Related Files