mirror of
https://github.com/penpot/penpot.git
synced 2026-09-25 05:16:14 +00:00
5c10ea5bd6
The creating-prs memory described a branch format (issue/... with a <type>/<short-description> fallback) that does not match actual repo practice, where issue-driven branches are issue-NNNN. Replace it with a Branch Naming section: issue-NNNN as primary, descriptive name without slashes as fallback. Add the matching public convention to CONTRIBUTING.md under Pull Requests, which previously defined no branch naming at all. AI-assisted-by: omen-alpha
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# Creating Pull Requests
|
|
|
|
PR only on explicit request.
|
|
|
|
## Branch Naming
|
|
|
|
- Primary: `issue-NNNN` — one branch per GitHub issue (e.g. `issue-11525`).
|
|
- No issue: free-form descriptive name, dash-separated, no slashes (e.g. `fix-ellipse-icon-typo`, `feat-auto-link-libraries`).
|
|
- If the user already created the branch, use it as-is — never rename.
|
|
|
|
## Target Branch
|
|
|
|
Auto-detect the base branch with `scripts/detect-target-branch`:
|
|
|
|
```bash
|
|
TARGET=$(scripts/detect-target-branch)
|
|
```
|
|
|
|
This outputs `staging` or `develop` by walking the local commit graph (pure local, no remote/network). Do not ask the user for the target branch unless the tool fails.
|
|
|
|
## Metadata
|
|
|
|
Always add the PR to the Main project (`--project "Main"`) unless the user explicitly requests a different project.
|
|
|
|
## Title Format
|
|
|
|
PR titles follow commit title conventions:
|
|
|
|
```
|
|
:emoji: Subject line (imperative, capitalized, no period, <=70 chars)
|
|
```
|
|
|
|
See `mem:workflow/creating-commits` for emoji codes. Squash merge uses the PR title as the final commit subject, so title format matters.
|
|
|
|
## Description Body
|
|
|
|
Include concise sections covering:
|
|
- what changed and why;
|
|
- related GitHub issues or Taiga stories (`Closes #NNNN`, `Relates to #NNNN`, `Taiga #NNNN`);
|
|
- screenshots or recordings for UI-visible changes;
|
|
- testing performed and residual risk;
|
|
- breaking changes or migration notes, if any.
|
|
|
|
PR descriptions follow this structure:
|
|
|
|
```markdown
|
|
**Note:** This PR was created with AI assistance.
|
|
|
|
## What
|
|
|
|
<the problem or feature and its user-facing impact — short bullet items where there is more than one point>
|
|
|
|
## Why
|
|
|
|
<root cause or motivation — a short paragraph or bullets>
|
|
|
|
## How
|
|
|
|
<high-level approach and key decisions — bullet items, grouped by area (bold lead-ins) for larger PRs>
|
|
```
|
|
|
|
The "Note:" line is required at the top. Adjust if this is a manual (non-AI) PR.
|
|
|
|
## Writing Principles
|
|
|
|
- **Write for humans.** The diff shows what changed. The description explains why.
|
|
- **Be concise.** Focus on reasoning: What was the problem? Why did it happen? How did you solve it?
|
|
- **Prefer bullets over paragraphs.** Short bullet items, grouped by area with bold lead-ins where helpful, are far easier to digest than prose; keep any remaining paragraph to a few sentences.
|
|
- **No manual line wraps.** Markdown renders adapting to the viewport; hard-wrapped lines degrade rendering. One line per paragraph or bullet, however long.
|
|
- **Skip the obvious.** Don't explain what `git diff` already shows.
|
|
|
|
### What NOT to Include
|
|
|
|
- ❌ List of files changed (visible in diff)
|
|
- ❌ Testing steps (CI handles this)
|
|
- ❌ Screenshots unless UI-visible
|
|
- ❌ Migration notes unless breaking changes
|
|
- ❌ Regression fixes introduced during the PR (they're part of the development process, not the feature)
|
|
|
|
## Before Opening
|
|
|
|
- Follow `mem:workflow/creating-commits` for commits
|
|
- Run the focused tests/lints appropriate to touched modules.
|
|
- Do not force-push during review unless the maintainer workflow explicitly asks for it.
|
|
- When the user says the code is already pushed, trust that — do not verify remote branch existence via `git ls-remote` or `git fetch`.
|
|
|
|
## Creating the PR
|
|
|
|
```bash
|
|
cat > /tmp/pr-body.md << 'PR_BODY'
|
|
<body content here>
|
|
PR_BODY
|
|
|
|
TARGET=$(scripts/detect-target-branch)
|
|
|
|
gh pr create \
|
|
--repo penpot/penpot \
|
|
--base "$TARGET" \
|
|
--head <branch> \
|
|
--title "<title>" \
|
|
--project "Main" \
|
|
--body-file /tmp/pr-body.md
|
|
|
|
rm -f /tmp/pr-body.md
|
|
```
|