Pull Requests

Review and merge code changes through collaborative pull requests with diff visualization and approval workflows.

Overview

Pull requests (PRs) provide a structured code review process before merging changes into the main branch. They enable:

• Peer review of workflow logic, prompt changes, and configurations
• Discussion via inline comments on specific changes
• Approval gates requiring sign-off before merge
• Integration testing to validate changes before deployment
• Audit trail of who approved what and when

M3 Forge’s PR workflow integrates directly with Gitea, providing a web-based review interface.

Creating a Pull Request

Reviewing a Pull Request

When assigned as a reviewer, you can inspect changes and provide feedback.

View Changed Files

The Files Changed tab shows all modified files with line-by-line diffs:

• Green lines — Additions
• Red lines — Deletions
• Gray lines — Context (unchanged)

For workflow JSON files, the diff shows structural changes to nodes, edges, and configurations.

Leave Comments

Click any line number to add an inline comment:

1. Type your comment
2. Optionally select Start a review to batch multiple comments
3. Click Add comment or Add to review

Comments can:

• Ask questions about implementation
• Suggest alternative approaches
• Point out potential issues
• Acknowledge good work

Example comment:

This prompt looks good, but consider adding an example
for the LLM to improve output consistency. See the
"few-shot prompting" pattern in our prompt guide.

Request Changes

If the PR needs work before merging:

1. Leave comments explaining what needs to change
2. Click Review changes
3. Select Request changes
4. Submit review

The PR author receives notification and can address feedback.

Approve

If the changes look good:

1. Click Review changes
2. Select Approve
3. Optionally add a summary comment
4. Submit review

Approved PRs can be merged (subject to repository settings requiring approvals).

Diff Visualization

M3 Forge provides specialized diff views for different file types.

JSON Diffs (Workflows)

Workflow JSON diffs show structural changes:

{
  "nodes": [
    {
      "id": "llm-node-1",
      "type": "llm",
-     "config": { "model": "gpt-4" }
+     "config": { "model": "gpt-4o" }
    }
  ]
}

YAML Diffs (Prompts)

Prompt YAML diffs highlight content and metadata changes:

---
name: "Extract Invoice"
-model: "gpt-4"
+model: "claude-3-5-sonnet-20241022"
temperature: 0.0
---
Extract invoice data from:
 
{{ invoice_text }}

Side-by-Side vs Unified

Switch between diff formats:

• Side-by-side — Old and new versions displayed in parallel columns
• Unified — Single column with +/- indicators

Use side-by-side for large changes; unified for small tweaks.

PR Lifecycle

Pull requests progress through several states:

Adding Commits to Open PR

If reviewers request changes:

1. Make updates in the same branch
2. Commit and push to remote
3. New commits appear automatically in the PR

Reviewers are notified of updates and can re-review.

Merging

When approved, merge the PR:

1. Click Merge pull request
2. Choose merge strategy:
   • Merge commit — Preserves full commit history
   • Squash and merge — Combines all commits into one
   • Rebase and merge — Replays commits on top of target branch
3. Confirm merge

The PR closes and changes are now in the target branch.

Deleting Branch After Merge

After merging, delete the feature branch to keep the repository tidy:

1. Click Delete branch button in merged PR
2. Confirm deletion

The commits remain in history even though the branch is deleted.

Approval Workflows

Repository administrators can configure approval requirements:

Require Approvals

Set minimum number of approving reviews before merge (e.g., 2 approvals required).

Dismiss Stale Reviews

Automatically dismiss previous approvals when new commits are pushed. Ensures reviewers see the latest changes.

Require Code Owner Review

For repositories with a CODEOWNERS file, require approval from designated code owners for specific paths.

Block Self-Approval

Prevent PR authors from approving their own PRs, enforcing independent review.

Integration with Release Pipeline

Pull requests are tightly integrated with the Release Pipeline:

1. Feature branch contains workflow/prompt changes
2. Open PR for review
3. Approve and merge to main
4. Create change set grouping related merged PRs
5. Create version from change set
6. Deploy version to staging/production

This ensures all production changes go through peer review.

PR Templates

Standardize PR descriptions with templates:

Create Template

In repository, add .github/pull_request_template.md:

## Summary
Brief description of changes.
 
## Motivation
Why is this change needed?
 
## Testing
How did you test this? What should reviewers test?
 
## Screenshots (if applicable)
Workflow canvas screenshots, execution logs, etc.
 
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Reviewed own changes
- [ ] Passed local testing

Use Template

When creating a new PR, the template auto-populates the description field. Fill in each section.

Best Practices

Small, Focused PRs

Keep PRs small for faster review:

• Single feature per PR
• Under 400 lines changed when possible
• Clear scope with no unrelated changes

Large PRs take longer to review and have higher risk of defects slipping through.

Descriptive Titles

PR titles should be concise but informative:

Poor:

Fix workflow

Good:

Add timeout handling to external API calls in fraud workflow

Detailed Descriptions

Include context reviewers need:

• What changed (summary)
• Why the change was made (motivation)
• How to verify it works (testing steps)
• Screenshots for visual changes

Review Your Own PR

Before requesting review, review your own changes:

1. Read through the entire diff
2. Check for debug code, console.logs, commented-out sections
3. Verify commit messages are clear
4. Ensure tests are included

Catch obvious issues before reviewers see them.

Respond to Feedback

When reviewers leave comments:

1. Acknowledge each comment
2. Explain your reasoning if you disagree
3. Make changes or start a discussion
4. Resolve comment threads after addressing

Reviewers appreciate responsiveness and constructive discussion.

Use Draft PRs

For work-in-progress, open a Draft Pull Request:

• Signals not ready for full review
• Enables early feedback on approach
• Prevents accidental merge

Mark as ready when complete.

Common Workflows

Hotfix PR

For urgent production fixes:

1. Create branch from main (e.g., hotfix/critical-timeout-bug)
2. Make minimal fix
3. Open PR with high priority label
4. Get expedited review
5. Merge and deploy immediately

Experimental PR

For trying new approaches:

1. Create branch with experiment/ prefix
2. Implement prototype
3. Open draft PR for feedback
4. Iterate based on discussion
5. Convert to regular PR if approved, or close if experiment fails

Documentation PR

For doc-only changes:

1. Create branch (e.g., docs/update-prompt-guide)
2. Edit markdown files
3. Open PR with reviewers from relevant teams
4. Merge after approval

Troubleshooting

Merge Conflicts

Cause: Target branch changed since PR was opened.

Solution:

git checkout feature-branch
git merge main

<<<<<<< HEAD
Your changes
=======
Main branch changes
>>>>>>> main

CI Checks Failing

Cause: Automated tests or linters failed on your changes.

Solution: Review CI logs, fix issues, push new commits. PR updates automatically.

Cannot Merge

Cause: Missing required approvals or failing checks.

Solution: Address reviewer feedback and ensure CI passes before merge button becomes available.

Next Steps

• Learn about change sets
• Set up repository approval workflows
• Integrate PRs with Release Pipeline
• Configure webhooks for CI/CD