Everything about how the dashboard sorts and labels docs PRs: the four groups, what a row's colors and tags mean, and how a docs PR typically moves from opening to merged.
The four groups
Every open docs PR sits in exactly one of these four groups. They answer one question: whose turn is it?
Need you today
Something only you can do right now: review a PR, remind the code author, follow up, escalate, do a final review and merge, or close a PR whose code changes got abandoned.
Bring it forward
Not urgent, but worth doing when you have time: a brand-new PR that still needs a label or milestone, a review on hold for its code PR to merge, or anything that's gone quiet for a while.
Waiting on others or for code PR to merge
You've done your part. Either the code PR hasn't merged yet (the docs PR is usually still a Draft while that's true), you've already sent a reminder, or you've escalated and are waiting for a reply.
Monitoring
The author replied and you've already answered back - a normal conversation is happening. This group is collapsed by default (click to expand it), but if one of its conversations goes quiet for a week, that row moves over to Need you today asking you to check in again.
Reading a row
Every row uses the same three visual signals, in this order: a colored bar on the left, a badge, and one or more colored tags.
Red: overdue, act on this first.
Orange: due soon.
Blue: something to do.
Dark grey: needs your review.
Green: approved and ready to merge.
Pale: nothing to do right now, it's on someone else, no matter what state the code PR or the docs PR itself is in.
Open A badge like this is a fact, not an action. It names the linked code PR's own state - Open, Merged, or Closed.
Draft A separate badge for the docs PR itself: it's still a GitHub draft. The docs PR is a draft while its linked code PR is still open - Promptless marks it ready for review automatically once the code PR merges. If you see this badge on a PR whose code PR has already merged, that automatic step didn't happen and someone needs to mark the PR ready by hand.
Review this docs PR A colored tag like this is an action for you. Its color tells you what kind of task it is - see below.
What the tag colors mean
Every tag of the same color is the same kind of task:
| Color | Meaning |
|---|---|
| Setup & triage | A brand-new PR that still needs a milestone. |
| Ask Follow up Escalate | The same color family, getting more intense the longer it's been quiet: a first ask, then a follow-up, then escalating to the Core Team. |
| Review / respond | Needs your direct attention: reviewing a standalone PR, checking an author's response, or looking at a note left after approval. |
| Finish & merge | The finish line: a final review before merging, removing a label that's no longer needed, marking a docs PR ready after its code PR merged, or an approval that's ready to go. |
| Backport first | Needs to be backportedApplied to every other still-supported release branch the underlying code change affects, not just the one this PR targets. before it can merge, or a note that this PR is itself a backport of another docs PR - see the backport scenarios below. |
| Manual attention | Needs a human judgment call: no code PR linked, someone's waiting on a reply, a rebase is needed, or the branch and milestone don't match. |
| Optional / already done | Nothing urgent: an early look at a still-open PR, a reminder you already sent, someone's looked but hasn't approved yet, Promptless replying to you, or a docs PR marked ready while its linked code PR is still open. |
| Close / dismiss | The docs PR should be closed - its linked code PR was closed without merging. |
| 🕸 Stale | Nothing has happened on the docs PR or its linked code PR for 30+ days - activity on either one resets the clock. |
The Priority filter
The Priority tab strip at the top of the dashboard lets you narrow the board down to one severity at a time:
| Priority | Meaning |
|---|---|
| Critical | You reminded the code author 14+ days ago and it's still quiet. Time to escalate to the Core Team. |
| Serious | 7 to 13 days of silence since a reminder, or someone's waiting directly on your reply. Send a follow-up. |
| Act | Something needs doing: review, remind, merge, or add a label. |
| Triage | A draft PR still waiting on its code PR, or a standalone PR waiting on its own author. |
| Stale | Nothing has happened on the docs PR or its linked code PR for 30+ days - activity on either one resets the clock. |
Critical, Serious, and Triage only narrow Need you today - picking one hides the other three groups. Act and Stale work differently: they show up across every group instead, since Bring it forward has actionable and stale rows of its own.
Docs review workflow
A walk-through of how docs review works, start to finish.
A new docs PR opens
- If the linked code PR is still open, Promptless creates a Draft PR. The PR does not have a milestone yet.
You'll seeAdd milestoneThere's nothing urgent yet. Once it has a milestone, it just waits on the code PR to merge.
-
You'll also seeReview this docs PRYou can review it early if you like, but there's no rush.
The code PR has merged
- If the linked code PR had already merged, Promptless opens a docs PR. If the docs PR was a Draft and the code PR merges while it's waiting, Promptless marks it ready on its own.
Occasionally, Promptless's automation doesn't fire, and it stays a draft. If it's still a draft:
You'll seeCode PR merged — mark ready for reviewMark it ready for review on GitHub by hand, then continue below. Once it's out of draft:You'll seeAsk code PR author to review content — code PR mergedThis is your cue to comment on the code PR, tag the author, and ask them to review the docs PR's content.
- The row moves to Waiting on others. You've done your part - nothing more to do here until the author replies or time passes.
- 7 days pass, still no reply.
You'll seeSend a follow-upPost a follow-up comment on the code PR, tagging the author again.
- 14 days pass, still no reply.
You'll see▲ Escalate to Core TeamTag the Core Team so they can help with reviewing the docs PR's content: on the docs PR, click the gear icon next to Reviewers in the sidebar, type
mautic/core-team, and select it from the list. - The author replies.
You'll seeCheck the author's responseRead what they said and reply back when necessary.
- The row settles into Monitoring once you replied. Nothing more to do unless it goes quiet again.
Someone approves the docs PR content
- The docs PR only merges once the code PR's author, a Core Team member, or a content reviewer approves it - either with a formal GitHub review or a clear approval left as a comment.
- Add the
content-approvedlabel as soon as someone approves the content - whether it's a formal GitHub review or a comment. A new commit automatically dismisses the approval, so the label keeps a record that the code PR author approved the content. - If the code PR has already merged, the row stays in Need you today.
You'll seeFinal review, then mergeDo a final review - check the grammar and wording - and approve the PR. Leave a comment and tag
mautic/education-team-leadersto merge the PR. - If the code PR is still open (the docs PR is usually still a Draft at this point), the tracker just notes the approval for now - docs don't merge ahead of code.
New commits reset an approval
If you haven't already added the content-approved label and GitHub automatically dismissed the approval the moment new commits land:
You'll seeAdd content-approved label — X’s review was dismissed
Add the content-approved label.
The docs PR is on the wrong branch
The docs PR targets a different branch than the linked code PR says it should.
You'll seeWrong branch — docs targets 7.2, should be 7.3 (code PR milestone 7.3)Add needs-rebase label
If it's still a Draft, add the needs-rebase label. If it's ready for review, ask Promptless to rebase it onto the branch named in the tag.
The docs PR needs a backport
The PR targets a version branch other than the one it should update.
You'll seeAdd needs-backport labelFinal review · backport, then merge
Apply an update from an older version branch to the newer branches too. The row names every branch that needs the same update, e.g. "targets 7.2 - also needs 7.3 and 8.0". Work through the whole list.
Before merging, ask Promptless to cherry-pick the changes onto the other branch(es) that need it. For example: @promptless-for-oss please cherry-pick the changes to [branch] branch.
A docs PR backported onto a second branch
A backport follows the original: every task - review, follow-up, merge - happens on the original PR, not the backport. That's why the backport's own row names the original's PR number instead of running its own clock.
Note: The PR numbers below are just examples.
- The backport PR opens. It carries #913's changes from
7.3to8.0.You'll seeBackported from #913 · 7.3 → 8.0 - Nobody's asked the code author to review the original PR yet.
You'll seeAsk code PR author to review #913
- The code author's been asked about the original, no reply yet.
You'll seeWaiting on #913's code PR author to reply
- The original merges.
You'll seeMerge — content already approved via #913Merge it - no separate review needed.
To ask Promptless for a backport, comment: @promptless-for-oss please create a PR to cherry-pick the changes here for [branch] branch.
The branch the docs PR needs doesn't exist yet
The docs PR belongs on a branch that doesn't exist yet in the docs repo - for example, the code PR is on
8.x, and the code repo already released branch 8.0, so the docs need an 8.1 branch that isn't there.
You'll seeCreate branch 8.1 in the docs repo firstAdd needs-rebase label
A PR can't point at a branch that doesn't exist, so create the branch in the docs repo first, then retarget the PR onto it.
The Core Team hands the PR back to the code author
- After an escalation, the Core Team asks the code author to review or confirm something themselves rather than answering it directly.
You'll see↩ Core Team passed back to authorIt's no longer the Core Team's turn. We're waiting on the code author's review again.
- 7 days pass with no reply from the author.
You'll seeSend a follow-upThis row won't escalate to the Core Team a second time. It keeps asking for follow-ups until the author replies or it goes stale.
Someone else jumps into the conversation
A contributor or another maintainer leaves a comment and nobody's replied yet.
You'll see👀 X is waiting on Y
The tracker sorts it as high priority if it's waiting on you; otherwise, it just sits there so you can keep an eye on it.
Promptless tags you and nobody's replied since
Promptless's latest comment tags you or a teammate - either confirming something you asked it to do directly (a rebase, a cherry-pick), or replying to an ordinary comment you left, which is sometimes a real suggestion worth a second look.
You'll see✅ Promptless confirmed something for X — worth a quick look
or👀 Promptless replied to X — worth a quick look
Promptless replies to almost everything, so this is often just a chore confirmation. It disappears once anyone replies.
The linked code PR gets closed instead of merged
You'll seeClose this docs PR
The documented change no longer applies. Close the PR with a comment such as: Closing this PR as the code PR is closed.
Nothing happens for a month
You'll see🕸 Stale
Nothing has happened on the docs PR or its linked code PR for 30+ days.
The reminders page
Docs PR review reminders is a separate page meant to be shared directly with code PR authors.
It lists every docs PR whose linked code PR has merged and where the ball is genuinely in the code author's court, grouped by author. Once the code author approves the docs PR, it disappears from this page - nothing left to ask them. Every row here gets one of two marks: Need review (the code PR has already merged, so this docs PR needs the code author's review), or Response to comment from X (the code PR author hasn't replied to X's comment yet).
Your checklist
Every row you can act on has a checkbox for your own tracking.
Checking it off is saved to your own browser only - nobody else sees it, and it doesn't notify anyone or change anything on GitHub or the tracker's own data. A checked row dims with its title struck through; clearing your browser data resets everything. A Hide checked rows switch next to the filters collapses checked rows out of view entirely instead of just dimming them.