Pull Request Workflow

A pull request is a collaboration feature provided by a hosting platform, not a Git commit type. The branch and commits exist in Git; the review conversation and status checks live on the platform.

Keep The Change Focused

A strong pull request has one clear purpose. It might fix an empty product name, add an order export, or update one dependency family.

Small, focused pull requests are easier to understand, test, review, merge, and revert. If the title needs several unrelated clauses, the work may need to be split.

Separate mechanical formatting from behavior changes where practical. Reviewers should not have to search through hundreds of whitespace edits to find a changed authorization rule.

Review Your Own Work First

Before requesting another person's time:

git status --short
git diff origin/main...HEAD

Then run the project checks and inspect the complete file list. Look for debug output, secrets, generated files, unrelated edits, missing tests, and stale comments.

A clean local result does not guarantee the pull request is correct, but avoidable failures should be caught before review.

Write A Useful Title And Description

The title should describe the outcome:

Handle missing product names in order summaries

A useful description answers:

• Why is this change needed?
• What behavior changed?
• How was it verified?
• Are there migrations, deployment steps, screenshots, or compatibility concerns?
• Which risks or decisions need reviewer attention?

A compact template is often enough:

## Summary

Explain the user or system outcome.

## Verification

- `composer test`
- `composer analyse`
- Manual check: describe the path and result

## Risks

State known risks, rollout needs, or `None`.

Do not paste a large generated summary without checking it. The author owns the accuracy of the description.

Draft And Ready States

Use a draft pull request when the branch is useful to share but not ready to merge. A draft can expose an approach, trigger CI, or invite early design feedback without pretending the implementation is complete.

Mark it ready for review only when:

• the intended scope is implemented
• obvious cleanup is complete
• relevant checks pass or failures are explained
• the description matches the current branch
• reviewers know what feedback is needed

Understand The Review Surface

Reviewers typically inspect:

• the description and linked issue
• commits and update history
• changed files and diff
• automated checks
• unresolved conversations
• merge blockers and approvals

Guide the reviewer when file order matters. For example, ask them to read a database migration before the repository implementation, then the tests.

Respond To Feedback Clearly

Treat review comments as technical questions, not commands to acknowledge mechanically.

For each comment:

1. understand the underlying risk or request
2. change the code or explain the tradeoff
3. add or update tests when behavior changed
4. push the new commit
5. reply with what changed and where
6. resolve the conversation only when it is actually addressed

Re-request review after substantial changes. Do not hide a large redesign inside an already approved pull request without drawing attention to it.

Use CI As Shared Evidence

Status checks may run tests, static analysis, formatting, dependency review, security scanning, and builds. Read the failing job and logs rather than repeatedly rerunning a deterministic failure.

A green CI result proves only what the configured checks cover. Manual verification and reviewer judgment still matter for user experience, migrations, operational behavior, and missing tests.

Keep The Branch Current Deliberately

If the base branch moves, update the pull-request branch using the repository's merge or rebase policy. Then rerun relevant checks because the integrated result may differ from either branch alone.

Avoid opportunistic history rewrites after review unless team policy expects them. Force-pushing changes commit identities and can make previous review context harder to follow.

Confirm Merge Readiness

Before merging, confirm:

• required checks pass
• required reviews are present
• requested changes are addressed
• conflicts are resolved
• the description and deployment notes are current
• the chosen merge method follows repository policy

Squash, merge-commit, and rebase merge strategies produce different history. Follow the project's convention rather than choosing based on personal preference at the merge button.

After merging, remove the short-lived branch when it is no longer needed and verify any required deployment or follow-up work.

What To Remember

A pull request packages a focused change for discussion and verification. Self-review first, explain the purpose and evidence, keep CI and the description current, respond to feedback explicitly, and merge only when the technical and process requirements are satisfied.

Before moving on, make sure you can write a useful verification section, explain when to use a draft, and distinguish a green CI result from proof that every risk is covered.

A Pull Request Is A Review Boundary

A pull request packages a proposed change for review, automated checks, discussion, and eventual integration. It is not just a button before merge. A useful pull request tells reviewers what behavior changes, why it changes, how it was tested, and what risks remain.

The best pull requests are scoped around one coherent outcome. A route change, database migration, template update, and test can belong together when they implement one feature. A dependency upgrade, unrelated formatting pass, and behavior change usually deserve separate pull requests. Smaller scope improves review quality and rollback options.

Prepare The Branch Before Opening

Before opening a pull request, run the checks expected by the repository: tests, static analysis, formatters, migrations, or build commands. Inspect git status --short, git diff --stat, and the actual diff. Remove debug output, local configuration, generated files that do not belong, and unrelated edits.

Write commits so reviewers can follow the work. Some teams prefer a polished series of commits; others squash on merge. Even with squash merges, local commits should not be so chaotic that the author cannot recover or answer review questions. If the branch is messy but unshared, interactive rebase can help organize it before review.

Write A Useful Description

A good description includes the problem, the chosen approach, validation performed, screenshots or examples where relevant, migration notes, and known follow-up work. For PHP applications, call out changes to database schema, Composer dependencies, environment variables, queues, public APIs, authentication, authorization, caching, and deployment steps.

Do not write "tests pass" if no meaningful test covers the behavior. State exactly what was run. If a check was not run, say why. Reviewers can handle honest uncertainty; hidden uncertainty creates risk.

Review As Collaboration

Review comments should be specific about risk. "This can double-charge after a timeout because the retry lacks an idempotency key" is actionable. "Use a better pattern" is not. Authors should respond by explaining, changing code, or asking for clarification; they should not treat every comment as a command when tradeoffs exist.

Reviewers should separate blocking issues from preferences. Security, data loss, broken tests, and incompatible API changes are blockers. Naming or formatting preferences may be suggestions, especially when automated tools can enforce them later.

CI And Required Checks

Remote checks give the team shared evidence. They should run the same commands the repository considers authoritative and should fail clearly. A required check that is flaky teaches developers to ignore red builds. A required check that does not cover the risky part of the change creates false confidence.

Branch protection should match workflow. Require review, require current branches, require passing checks, and restrict direct pushes where the team needs those controls. Avoid bypassing protection for convenience; if bypass is necessary during an incident, document the reason and follow up.

Updating A Pull Request

When the base branch moves, fetch and integrate deliberately. A merge from base preserves the branch's existing commits and records the integration. A rebase rewrites the branch commits onto the new base. Follow team policy and avoid rebasing a branch that others are using without coordination.

After addressing review comments, make the change easy to re-review. Some platforms show only new commits since the last review. If you force-push a rewritten branch, leave a comment describing what changed. Use range-diff when a rebase substantially rewrites reviewed commits.

Merging And Aftercare

The merge method affects history. Merge commits preserve branch structure. Squash merge creates one commit on the target branch. Rebase merge creates a linear series. Choose the method the repository expects, and make sure the final commit message is useful because it becomes part of the long-term history.

After merge, delete the remote branch when it is no longer needed, confirm deployment or release steps if the pull request included them, and track follow-up work explicitly. Do not leave "temporary" flags, migrations, or compatibility code without an owner.

Handling Risky Pull Requests

Large or high-risk changes need more structure. Split schema changes from behavior changes when backward compatibility requires it. Add feature flags when rollout needs separation from deployment. Include rollback or roll-forward notes for migrations, background jobs, and public API changes.

For security-sensitive changes, avoid publishing exploit details in public repositories while still giving reviewers enough context. Use private advisories or restricted descriptions where appropriate.

After this lesson, you should be able to prepare a focused pull request, write a reviewable description, use CI and branch protection as shared evidence, respond to review effectively, update branches safely, choose a merge method deliberately, and plan aftercare for risky changes.

# Handle missing product names in order summaries

## Summary

Order summaries now display `Unknown product` when an older product record has no name. The change is limited to the summary label helper and its unit test.

## Verification

- `composer test` - passed
- `composer analyse` - passed

## Risk

The main risk is changing labels for valid named products. Please check that the existing-name path remains unchanged and that the fallback is used only when the key is absent.

## Deployment

No migration or special deployment step is required.