Today's English Expression 11/30 · Category: PR Description. All examples are created for this post. They are not taken from real repositories, and feature names are examples.
Table of Contents
- At a Glance
- 1. Meaning and Nuance
- 2. Examples
- 3. Similar Expressions and Differences
- 4. Common Mistakes Made by Koreans
- 5. One-line Practice
- Sample Answer
- References
At a Glance
| Expression | Marking this as a draft until ... / This is ready for review. |
| Meaning | Keeping this as a draft until ... / It is now ready for review. |
| Where to Use | Beginning of a PR description, PR comments, Slack |
| Politeness | Neutral. It is a status update statement. |
1. Meaning and Nuance
Draft means a preliminary version. According to GitHub docs, draft PRs cannot be merged, and review requests are not automatically sent to code owners. When it is ready, you change it to Ready for review, and review requests are sent to code owners at that time. You can also switch it back to a draft at any time.
Therefore, opening a PR as a draft sends the signal: "Looking is welcome, but a thorough review is not needed yet" You use it when you want to check if the direction is right first, when you want to see CI results, or when you are waiting for a preceding PR to be merged. The key here is to include what you are waiting for(until ...). If you leave it as a draft without a reason, reviewers won't know when to check it again.
The Kubernetes contribution guide advises adding WIP or [WIP] to the title of a PR that is not ready for review. WIP stands for work in progress, and the Prow bot adds the do-not-merge/work-in-progress label to block merging. Also, the /hold command adds the do-not-merge/hold label to prevent approved PRs from being merged. It is also recommended to open a draft PR and ask for guidance when you are unsure, such as for large changes or auto-generated changes.
2. Examples
Situation 1: At the beginning of a PR description
Marking this as a draft until #3200 is merged, since this PR builds on top of it. Early feedback on the API shape is welcome.
"Builds on top of" means it relies on a preceding PR. "Early feedback is welcome" clarifies the purpose of opening the draft.
Situation 2: When you are done
This is now ready for review. I've rebased onto main and added unit tests for the new validation.
Writing a line about what has changed after switching from a draft helps reviewers know where to start looking.
Situation 3: Asking about direction on Slack
I opened a draft PR for the snapshot export feature. It's not ready for a full review yet, but I'd appreciate a quick look at the overall approach.
3. Similar Expressions and Differences
- WIP / [WIP]. A label added to the title. It is a convention used since before GitHub's draft feature existed, and some repositories like Kubernetes have bots that read this.
- Not ready to merge yet. Means reviews are okay, but please wait to merge. Unlike a draft, a review is officially requested.
- /hold. A command in repositories using Prow that only blocks merging. To remove it, use
/hold cancel.
4. Common Mistakes Made by Koreans
- Not completed yet. Please wait. It does not state what is being waited for or when it will be finished.
- Corrected sentence: Marking this as a draft until the e2e tests pass.
- Please don't review this PR. Negative commands sound awkward in public repositories since anyone can see them.
- Corrected sentence: This isn't ready for a full review yet, but early feedback is welcome.
- I changed it to ready. What it is ready for is missing after ready.
- Corrected sentence: I've marked this as ready for review.
5. One-line Practice
Rewrite the following Korean sentence as the beginning of a PR description.
Keeping this as a draft until documentation is done. Code feedback is welcome now.
Sample Answer
Marking this as a draft until the docs are done. Feedback on the code is welcome in the meantime.
"In the meantime" means during that time. Translating "you can give it now" as "is welcome" makes it an inviting remark without putting pressure.
Titi's Tip. Always include "until when" in a draft so reviewers know when to return.
References
- GitHub Docs, About pull requests (Draft pull requests): https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
- Kubernetes Contribution Guide, Pull Request Process (WIP, /hold): https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md