Skip to content

Commit f7bc1c5

Browse files
authored
Update the maintainer instructions wrt blessing (DefinitelyTyped#52884)
1 parent 4ba4f06 commit f7bc1c5

File tree

1 file changed

+22
-15
lines changed

1 file changed

+22
-15
lines changed

docs/admin.md

+22-15
Original file line numberDiff line numberDiff line change
@@ -26,21 +26,6 @@ Some key concepts:
2626
- There are a handful of authors who have shipped a lot of high quality contributions who you can happily delegate to
2727

2828

29-
##### "Blessing" a PR
30-
31-
If a PR looks kind of ok, but you don't want to submit an approving review (it can be mistaken as an expert approval),
32-
then move the PR *away* from the `Needs Maintainer Review` and the bot will interpret that as an implicit blessing. (Do
33-
this using the dropdown column in the "Projects" box on the right.) Like reviews, updates to the PR will void such a
34-
blessing.
35-
36-
The column you move it to doesn't make any difference to the bot, it will move it to the right one if needed, but it
37-
works best to move it to `Waiting for Code Reviews`.
38-
39-
> **Disclaimer:** It is currently impossible to get from/to information about column moves, so the bot ignores the
40-
> column it was moved from. This means that it is impossible to cancel a blessing, but you can still submit a review if
41-
> changes are needed.
42-
43-
4429
##### Project board columns
4530

4631
- `Needs Maintainer Action`: PRs that cannot be dismissed with a blessing
@@ -50,6 +35,28 @@ works best to move it to `Waiting for Code Reviews`.
5035
- `Needs Author Action`, `Recently Merged`, `Waiting for Code Reviews`: Self describing
5136

5237

38+
##### "Blessing" a PR
39+
40+
You can control the life-cycle of PRs via "blessings", which are implicit operations done without providing a review that can be misinterpreted as an expert review.
41+
42+
> TL;DR:
43+
> * To dismiss a PR in "Needs Maintainer Review", move it to "Waiting for Code Reviews".
44+
> * To dismiss a PR in "Needs Maintainer Action", move it to "Waiting for Author to Merge".
45+
> * To undo either of these, move them to any other column.
46+
47+
* If a PR requires a *maintainer review*, you can fulfill this requirement by a "review-blessing": you do that by moving the PR to the `Waiting for Code Reviews` column (using the drop-down in the "Projects" section on the right).
48+
This is especially relevant in cases where a maintainer review is needed because of a technical requirement like no tests, suspicious config edits etc: in such cases you can review-bless the PR in case the config edit is fine, the change is small or doesn't modify types etc.
49+
Note that it only dismisses the maintainer review requirement, so the PR will continue the usual flow, and will wait for approvals as needed.
50+
51+
* If a PR requires a *maintainer action*, you can move it to the `Waiting for Author to Merge` column to "merge-bless" it: make the bot offer the author to self-merge.
52+
This is particularly useful in cases where a PR author is unsure about something, and is trying to solicit review from owners or library authors: it makes it possible to defer the decision when to merge to the author, instead of starting an "are you ready" discussion.
53+
54+
You can use either of these blessings in other cases too, the above are just the common use cases. A review-blessing is only good to satisfy a maintainer review requirment (so other reviews will be needed), and a merge-blessing will usually make a PR self-mergable, but it will still wait until a PR is unconflicted and the CI is green.
55+
56+
Like a review, both kinds of blessings will be dismissed if the PR is updated.
57+
You can also undo a blessing by moving a PR to any other column.
58+
59+
5360
##### Amending an existing Definitely Typed Package
5461

5562
An ideal PR to a DT package looks like:

0 commit comments

Comments
 (0)