Make it clear that "PENDING" comments have to be submitted

[medallyon]

It just took me 2 months to figure out that the big, yellow "PENDING" decorator on my comments does NOT mean:

"Your comment is pending to be reviewed by the maintainer."

But it actually means:

"You haven't submitted your comment (along with your review)."

It took me some additional days to figure out how to "submit" the review. I was merely commenting on a review that the maintainer had already started and expected those comments to appear on the reviewer's end as soon as I clicked on "Comment".

See the following:

[stpaultim]

It took me some additional days to figure out how to "submit" the review.

@medallyon - Any chance you would be willing to share what you learned? How do I properly submit my review so that these comments go away?

UPDATE:

After much looking, I found the place to "Submit" my review on the "files changed" tab in the upper right hand corner.

[egouldo]

I'm still a little confused. So if I have pending suggestions / comments, when I submit my review, should I choose 'comment', 'approve' or 'request changes' ?

[larryrivera-ca]

terrible wth

[reeses1]

Chiming in. This resulted in a change request going unnoticed followed by a code merge. Meanwhile I'm staring at the comment completely perplexed as to how it got missed. Thanks to folks who investigated this -- definitely could use improvement.

[Roldanlautaro]

wow

[stpaultim]

Two years later - I just spent the weekend creating but not submitting responses on a PR I wrote. Everyone was wondering, why I had nothing to say.

Very frustrating.

[ghost]

Having to submit my replies to comments on my own PR is very unintuitive in general. But I agree with the original post, it should be more clear that you're in a 'session' that needs to be closed.

[uchagani]

just ran into this myself. horrible experience

[MichaelHeinzman]

Same, it was pending for a few days and then the person who submitted the pr said he couldn't see it. Definitely needs more clarity.

[Marenz]

This annoys me so hard every single time. And there isn't even a shortcut to submit. CTRL+Return submits it as Pending comment, too, starting a review. ON MY OWN PR.

[kamkry]

Please fix it, I want to reply to other comments without submitting my review yet

[Rashidkhan1234567]

Whats problem bro ?

[PetrGlad]

@Rashidkhan1234567 No one can see your comment until you submit a review of this thread.

[vaix-ducvn]

hello

[ChefCupcake]

what?

[mjang]

Yeah... this is mega confusing for newer GitHub users. Here's an example where a newer user tells me "But Mike, I've reviewed your PR." And except for the "pending" label, it looks like it!

Seriously. "Pending" is a poor choice of words. For so many GitHub users, "pending" sounds like legalese. I'd replace "pending" with something like:

• "not yet submitted"
• "draft"

Or maybe with an (i) (info) pop-up that says "To share your comments with the author, select Review changes" (or "Finish your review", depending on the status)

[ailinz22]

YESSSSS!! So True! The pending is so misleading that I thought it was pending because the commenter hasn't viewed my new response yet...I thought it would be automatically changed after he read my reply...

[pantherdd]

I totally agree, and IMO "Draft" is the right word to use. With a tooltip explaining what it means!

[NovaAndrom3da]

draft would be the PERFECT word to use in this scenario... i don't see why this hasn't been changed yet...

[mjang]

Since @github-staff has yet to respond, I've posted a related Tweet: https://twitter.com/TheMikeJang/status/1562789398034276353?s=20&t=Q9Law9XkEM4WagPewd7AaQ

[vpithart]

I've fallen into the same pitfall after a few years not using githuvb reviews 🤦 The pending word feels really misleading.

Inspiration: the slackbot's only visible to you would be by far easier to grasp for first-time users.

[GollyTicker]

Yes! Please let's do this!

The current wording with pending is very misleading, as one can interpret it as "a response from the others is pending". And it's totally not clear, that such pending reviews need to be published.

[dganzella]

Voice of reason here!

[rollSUgrem]

such a freaking flow. If you just press green button "add review comment" doesn't mean you actually make a comment, you have to submit your comment as well... omg

ps should I submit something after pressing "answer" button here?

[thomasbnt]

Ow please yes, change that to be clear in comments. I requested some reviews, but I didn't realize is marked "Pending". 😄

[njmulsqb]

Happened to me as well, I replied to the reviews and after many days the maintainer made me realize that my comments are PENDING and not even visible to them. Really bad design, Github should definitely make it more intuitive

[tonesandtones]

Yep that just got me too. Here I was wondering why my colleagues hadn't addressed my comments ... because of course they hadn't seen them.

Yet another way I dislike Github's PR experience 😡

[zyiyi11]

I just realized it today after 2 months of being neglected of the reviews...

[laglangyue]

yes, I meet it

[oviliz]

This is just incredible...

[melvic-ybanez]

The first time it happened to me, my teammate had to message me that he didn't see my comments on his PR. (I was glad I told him I wrote some comments, or I wouldn't have figured it out.) And sometimes my comments would become outdated by the time they are submitted, because the user had already updated the code.

[suyj-git]

Same happens to me..

[FocusriteMGreenwood]

Just came across this myself. It almost caused a PR to be merged without significant issues being addressed.

Dear GutHub. Wording matters. Whatever "Pending" means in your heads is not what it means to a majority of your users. This is a very poor choice of words and there are plenty of better suggestions in this report. Just pick one that makes it clear the comment has not yet been submitted, because most people seem to assume that once you finish editing the comment that it has been submitted. The final step where you have to "add your review" is really not at all clear.

[ivandres73]

Ran into this today, because my comment was not visible a PR was merged introducing a bug to the main branch.
The problem is not how it works, is the text "Pending". When I saw my comment was "pending" I assumed it meant: "it is pending to be addressed by the PR author".

Just change the text! that shouldn't be super hard, is a label!

[NovaAndrom3da]

This is a one-line fix, how hard could it possibly be to fix this to both A) ease tensions from your users and B) prevent this issue from arising with hundreds of future users? It's been years, I'm certain anyone in this thread could've fixed this in a tiny fraction of that time. It would take maybe 5 minutes, at most.

[tsoj]

I have the suspicion that the github team just forgot about this.

[Radivarig]

They didn't forget, they commented but didn't submit it.

[krupenkov-e]

Guys, be patient. Github is a small indie company, they neither can address every little(or major) issue quickly nor afford a decent UI/UX designer. One day they'll fix it

[FocusriteMGreenwood]

GitHub is owned by Microsoft! Hardly a small indie company :D

[nobody0]

GitHub is owned by Microsoft! Hardly a small indie company :D

MICRO soft, its such a small company, they even put it in the name

[izmyname]

Well, good to see I'm not the only who got into this silly situation.

[dganzella]

seriously, fuck this shit, almost went through a shitstorm here because things were taking weeks to be reviewed

also why the fuck some things become pending and others do not?

my brothers in christ, what the hellllll, I dont care about your fucked up process, do whatever shit you want, but for fucks sake, do like any other fucking software or social network and straight up just write in giant letters

"ONLY VISIBLE TO YOU"

[HarmonyMorse]

Seriously. Like "pending" can mean so many different things. Just make it clear.. please

cries in the corner

[ik-ivanov]

Just went trough the same ordeal. Boy, this was mighty confusing! 😢

[nerdCopter]

I've decided this is a bug 😉
https://support.github.com/request >> bug report or other support >

Product

GitHub

Description

This subject seems to have been overlooked or ignored and needs attention:

    https://github.com/orgs/community/discussions/10369
    PENDING is 100% unclear. Please consider replacing the text with DRAFT or some other pertinent terminology.
    It is not 100% clear that one must "finish" a review.

Reproduction Steps

    Click the "+" icon/button on any code of any PR.
    make any comment
    Click Add single comment or Start a review.
    Do not click Review changes, do not click request changes, approve nor comment.

The unfinished review shows PENDING, which is not 100% clear to user and hidden to every other user/maintainer.

Fault Type

Permanent - Occurring repeatably

Blocking?

No

Last working date

Logs

Maybe you all have decided the same 😉

[dganzella]

Thanks! Hopefully they change it.
I mean we are vaccinated against this issue already, but will help people in the future

[HarmonyMorse]

It certainly blocked me when my comments weren't getting reviewed by team members.

[nerdCopter]

dead-end; circular.

screencap

[ICEknigh7]

Maybe tell Rocky that it doesn't matter if it's intended when it's a problem.

[nerdCopter]

my reply was blocked due to ticket closed. ☹️

[szalapski]

It just seems so obvious that the point of comments is to be seen. The price of showing your comment a little too eagerly IS NOTHING compared to the price of never seeing the comment at all. This isn't a poker game--we can show our hands to each other. Let us get rid of the "Pending" status altogether (in a repo-wide or org-wide setting if you must). It's that easy!

Please let me reiterate: no other code review tool does it this way and it is the most astonishing design decision that keeps biting us over and over again.

[MrQubo]

It happened to me a second time already, I've left a comment on a line of code in PR, but no one ever saw it, because I clicked the "Start a review" button.

The problem is that the in the UI there's a very small visual distinction between submitted and pending comments. The only difference is "Pending" word. I though "Pending" means that the author is yet to resolve and answer the comment. In no way UI suggests that the comment is visible only to me and no one else.

I have some suggestions on how to improve UX of that feature:

1. Make the pending comments more visually distinguishable from non-pending ones. Though maybe that's not needed if other suggestions were to be implemented.
2. It should be explained that the comments aren't visible to anyone until review is submitted. E.g. when clicking "Start a review" (only for the first time, and after not using the feature for a few months, so users using that feature commonly can skip this additional text box). Alternatively add some "You're yet to submit your review!" warnings somewhere in the comments section.
3. Notify the user if he has pending review comments that weren't touched for more then few hours/days (configurable?). Alternatively issue warning if the user tries to close tab with pending review in it (possibly with a setting to turn it off).

There are also other very good suggestions in this thread...

[MrQubo]

This caused a buggy PR to be merged, see NixOS/nixpkgs#331722 (comment)

[MrQubo]

Nowadays GitHub has a separate button "Add single comment" that submits comment immediately. But this didn't fix the issue. "Pending" is still unclear and "Start a review" also doesn't clearly communicate that the comment won't be visible.

It would be much better to replace "pending" with "draft", and "start a review" with "make draft comment".

[richcarl]

FOR FUCKS SAKE GITHUB!

[binhpham-dklab]

Learned this the hard way yesterday...

[pantherdd]

I liked the idea of @nerdCopter above, and decided to also file a bug report myself. You should probably all do the same if you agree that this needs to be fixed, given that it has been stated by @queenofcorgis above that this discussion is ignored by Github.

---

Draft reviews have a misleading name ("pending") #3149992

Product

GitHub

Description

When we start writing a review on a pull request, its existence starts as a draft. In this state, we can edit, amend, add or remove comments. Once we're done, we submit the review.

This temporary state is called "draft" in every tool all over the planet (e.g. GMail), and everyone knows what this state means: that I, the author, have not finished, finalized, submitted it, and that it is me, the author who needs to take the next step.

Github, for some reason, is incorrectly calling this temporary state "pending", which is confusing users. The problem with this word is that "pending" does not imply who needs to take that next step, and in real-world applications, it almost always means that it's not me, the author, but someone else. There is also no tooltip or explanation in the UI where it shows "pending", no help as to what it means, so people assume that it's the other party who needs to do something about the review.

We, who already got burnt because of this misleading name, know that this bug is documented, but actually fixing it would serve the world much better. Just replace the misleading word "pending" with the clear & obvious "draft" both on the UI and in the docs, like so:

Before you submit your review, your line comments are drafts and only visible to you. You can edit draft comments anytime before you submit your review. To cancel a draft review, including all of its draft comments, click Review changes above the changed code, then click Abandon review.

Seriously, look at this discussion: https://github.com/orgs/community/discussions/10369
All these comments and upvotes are from users who have suffered from this poor naming. And there are probably thousands more, who never even realized their mistake, or did not bother to write to you because this problem is obviously being ignored for years now.

Fix it.

Reproduction Steps

1. Start writing a review on a pull request, but don't submit it.
2. Forget that you, as Github experts, have the domain knowledge already that this review is only a draft at this point, and needs to be submitted before anyone else even gets to know about its existence.
3. Look at the UI. It will say that the review is "pending". Hover over the tag, and check that there is no explanation as to what this means. Apply your general knowledge built up over the years as a software developer, and make an educated guess about who needs to take the next step to conclude the review. Remember point 2. above, your only clue is the word "pending"!
4. Once you have reached the conclusion that the review must be "pending some action by someone else, most likely the author of the pull request", you have successfully reproduced the bug.

Fault Type

Permanent - Occurring repeatably

Blocking?

No

Last working date

Logs

Logs from the affected processes (your users, i.e. customers) can be seen at: https://github.com/orgs/community/discussions/10369