When creating a discussion (either by creating the first comment, or converting an existing comment), optionally indicate that it is resolvable.
When you resolve the discussion, you truly resolve the entire thing. There is no concept of individual comment resolvability.
This applies to issues, merge requests (non diff), commits, and snippets.
If a single root comment has no replies, we still show the reply panel so a user can easily reply, resolve, jump to the next discussion, and make an issue from the unresolved comments.
@tauriedavis continuing from my comment about the collapse/expand button, I don't think it should be at the same “level” as the actions to interact with the discussion (“Create issue for discussion” and “Jump to next discussion”). Now that I look at this, it makes me want to put the “Reply” and “Mark as resolved” actions with the same visual weight as the button actions, after all these are the most important actions one can have with the discussion.
I'm thinking about a single place with all of the actions, instead of two lines (at least when collapsed). I don't have any particular suggestions (sorry), I guess it's something to experiment with.
@tauriedavis The “Create issue for discussion” and “Jump to next discussion” options really only make sense for unresolved discussions that are expanded by default, so what do you think about only showing those when the discussion is expanded, not when it's collapsed?
I don't think I don't think we need the extra "Expand/Collapse" button, I think the one on the main discussion is fine. People are more likely to expand a collapsed discussion than the other way around, which they can do by clicking anywhere in the "2 replies" widget already.
I've updated the description based on everything we've discussed.
If a single root comment has no replies, we still show the reply panel so a user can easily reply, resolve, jump to the next discussion, and make an issue from the unresolved comments.
@tauriedavis yup, that sounds/looks great. Should the checkbox label be “Mark comment as resolvable” to be consistent with the dropdown option? Also, wouldn't it be preferable to verb that option as “Mark asMake it resolvable” to differentiate making a comment resolvable from marking a comment as resolved? And finally, what's the option label for reverting the resolvability of a comment?
I think we have an opportunity here to be more opinionated and simplify our product and encourage best practices in collaboration. I'm thinking that all discussions must be resolvable. (And so when you first start such a discussion, it starts out as unresolved.)
In very long issues with complicated designs and ideas, discussions can go many places. We want a bit more structure and control. Discussion threads provide this.
But if we enforce that all threads must be resolvable, which I'm suggesting, it further encourages directed conversations that help direct collaboration to a goal. At the same time, free-flow brainstorming is still possible with non-discussion comments. And you can still have a free-flow thread. But you can purposely leave it unresolved if it is intended to be open-ended.
If we maintain that all discussions must be resolvable, then that simplifies the design (one less optionality) and we don't need to worry about making a discussion resolvable after the fact or forgetting to make it resolvable in the first place.
This would also be consistent with MR diff discussions, which are already resolvable-enforced. (The only difference is that those discussions are per-comment resolvable, which we do not want here.)
But if we enforce that all threads must be resolvable, which I'm suggesting, it further encourages directed conversations that help direct collaboration to a goal. At the same time, free-flow brainstorming is still possible with non-discussion comments. And you can still have a free-flow thread. But you can purposely leave it unresolved if it is intended to be open-ended.
@victorwu If all discussions are to be resolvable, without a way to toggle resolvability, I suggest we split the following step into its own issue:
Enabling resolving on noteables other than MR. The code is already there, we likely just need to remove a bunch of "if merge request" checks.
This would require no new UX, and relatively little work on the FE and BE, because we just need to apply what we've already done on MRs to the other issuables.
I think it's a good idea to remove the optionality.
I think that's a good feature, but definitely a separate iteration. It would also introduce additional friction into closing issues. So we might be forced to introduce a configuration for it. I'm not sure. So in any case, we have to be careful of how we design it.
But beyond blocking closing an issue, there's several potential use cases that I can see we can build on top of resolved / unresolved discussions:
You can view/jump to unresolved discussions, just like merge requests. So it immediately becomes like a task list and can serve that workflow of having a dynamic list of things that need to be done/addressed.
Instead of blocking an issue from being closed, we can use it as a more general gating mechanism, similar to approvals. See &364.
@tauriedavis : Sorry. I should use more specific language. I mean like in merge requests, you can block it from being merged based in WIP, approvals, and pipelines (and maybe some other features I forget). So these are gates to prevent the merge request from advancing to the merged state.
With issues, we only have open state and closed state. We have additional "workflow stages" with labels in a board. But these aren't first class citizens. The concept of &364 is to make workflow stages a first class citizen. And so once we have that, we could consider introducing ways to control an issue flowing between these stages, just like mrs.
@tauriedavis : I'm trying to figure out how to split up the work and I wanted to confirm the ideas in your designs.
Based on previous discussion here and in https://gitlab.com/gitlab-org/gitlab-ce/issues/30299, we want to retain the ability to submit a brand new comment as a discussion. I.e. right now the comment button is a dropdown with two selections. We want to retain this feature even after we can turn a standalone comment into a discussion.
So I believe we want to support all these cases:
With one action: Submit a comment as a standalone comment.
With one action: Submit a comment as a one-comment discussion.
With one action: Convert a standalone comment into a two-comment discussion by "replying" to it. (I.e. the Slack case.)
We may want to support this case, but it'll take extra UI I think so let's not worry about this now:
With one action: Convert a standalone comment into a one-comment discussion.
So if the above all makes sense, we need to differentiate between a standalone comment versus a one-comment discussion. And the reason this is necessary UI-wise is because a standalone comment is not resolvable. (Resolvability doesn't apply to individual comments.) And a one-comment discussion is resolvable. In particular the use cases justify the differences:
Standalone comment: This is a free-flow comment. But another person may want to start a convo on it, thus, turning it into a discussion.
One-comment discussion: This is the case where the person is inviting a discussion. For example, someone might say, @tauriedavis: What do you think about this concept? Could you please respond in this thread and resolve if you agree?
So looking at your mockup in the description here, I think the first visual should be the standalone comment case, and the second visual should be the one-comment discussion case. I.e. when you have a one-comment discussion, there's a reply box that already appears, and a resolve button already there, inviting you interact with it. With a standalone comment, you need to actively click the speech bubble icon in order to bring up the reply box in the first place.
I agree with @jk, I don't see a reason for the added complexity. Why not just have a comment button and then people can respond to it? I don't think we need to allow users to choose between creating a comment or a discussion from the beginning.
@tauriedavis : If the very first comment is always just a standalone comment, then it won't be a resolvable discussion. I agree that it would simplify the UI a bit, but we do miss out on the use case of initiating a resolvable discussion at the beginning. See the use case I described in https://gitlab.com/gitlab-org/gitlab-ce/issues/32451#note_106926920.
The workaround would be that anybody who wants to initiate a resolvable discussion would have to reply to their own comment right away. Alternatively, we could keep this ability the choose Start discussion in the dropdown. But GitLab would automatically post two comments for you when you click that choice.
I think @DouweM felt strongly about having discussions right from the start. Douwe: Is that correct? Please correct me if I got it wrong.
@tauriedavis : Since we said above we want all discussions to be resolvable. (And so I think standalone comments should not be resolvable.) So if that's the case, could we tweak your design so that you can take a comment, and turn it into a discussion.
@victorwu@tauriedavis it seems like we are running in circles here I think everyone agrees that standalone comments should not be resolvable, as they may not necessarily require a reply or resolution. If someone replies to one of those comments, it automatically starts a discussion that has the possibility of being resolved (resolvability is not required, yet).
I'm wondering if the issue has to do with the terms. In the mockups we have Mark as resolvable and Make this comment resolvable — which approaches this as setting the resolvability of the comment. You are suggesting Turn into discussion — which approaches this as transforming one thing into another, and doesn't mention anything about resolvability. I think the mockups approach this from a more correct POV, the end goal of the user: “I think my comment needs to be addressed/resolved and would like to encourage a reply.” What about:
Comment area checkbox: This comment needs to be resolved
Dropdown: Mark need for resolution and Unmark need for resolution
Note that once a comment has been replied to (and turns into a discussion), it's no longer possible to remove the resolvability.
I aggree with @pedroms. The dilemma between "discussion" and "comment" is wrong. The point is the resolvability. So, ... lets forget about these and distinguish between top-level comments and replies to the top-level comments. The difference is that one cannot reply to a reply; instead, the one's reply is simply an another comment in the thread started by the top-level comment.
Now, when everything is simple, just add the "needs to be resolved" and "is resolved" flags to everything or to whole threads only.
If someone replies to one of those comments, it automatically starts a discussion that has the possibility of being resolved (resolvability is not required, yet).
I think @DouweM felt strongly about having discussions right from the start. Douwe: Is that correct? Please correct me if I got it wrong.
@victorwu I feel strongly that there should be a way to indicate "I think my comment needs to be addressed/resolved and would like to encourage a reply.", as @pedroms phrased it. I think we're all in agreement on that :)
Note that we currently use the phrasing "(un)resolved discussion(s)" in a bunch of places, which could be confusing if we can have individual resolvable top-level comments that don't look like discussions.
Note that we currently use the phrasing "(un)resolved discussion(s)" in a bunch of places, which could be confusing if we can have individual resolvable top-level comments that don't look like discussions.
Agreed. Doesn't it all go away if all discussions need to be resolved and if you want the comment to be resolved, just transform it into a discussion?
Turn into discussion (required to be resolved)
^ some sort of UI speaking navigation thing can help in communicating that effect.
That seems overly complicated. The user shouldn't need to know the difference between a comment and a discussion in order to resolve something.
A user posts a comment, and either
A) Wants a reply
B) Wants an action to be followed up on
C) Wants their opinion voiced with no follow up needed
A user reads a comment, and either
A) Wants to reply to it
B) Wants to complete the action item
C) Wants to ignore it
The comment/discussion distinction is a technical distinction that doesn't involve the user. "(Un)resolved discussions" doesn't seem like a big deal to me but if there is confusion, then just saying "(Un)resolved comments" would make sense. You just have comments that you are able to reply to. You can only resolve the entirety of the thing, either the comment or the comment that happens to have replies.
We shouldn't put the burden on the user to know that a comment needs to be deemed "a discussion" in order to create an action item that needs to be followed up on.
"(Un)resolved discussions" doesn't seem like a big deal to me but if there is confusion, then just saying "(Un)resolved comments" would make sense. You just have comments that you are able to reply to. You can only resolve the entirety of the thing, either the comment or the comment that happens to have replies.
@tauriedavis exactly what I think. What we are effectively resolving is the first comment, the comment that starts the discussion, that's the object/thing that needs to be resolved/addressed — if we call it “(Un)resolved discussion” or “(Un)resolved comment”, I think that's not a big deal. Let's implement something and iterate.
Users add comments.
Comments can be standalone or in reply to other comments. All standalone comments accept replies.
An author of a standalone comment can indicate if it needs to be resolved. This encourages other users to reply with other comments.
A comment thread (the union of a standalone comment and its replies) is a discussion. These are always resolvable, regardless of the standalone comment being marked with “need to be resolved.” This means that even if its author has not marked it with “need to be resolved” and someone replies, it now becomes resolvable.
Anyone with permissions can resolve when they consider that the standalone comment has been addressed. We may say that the “comment has been resolved” but it's also fine to say that the “discussion has been resolved” (I don't have a strong opinion on this, yet).
This is already visible from the mockups but wanted to have it detailed regardless:
I feel from a issue discussion perspective it would make sense to have resolving capabilities as well. The difference being that when a discussion has been collapsed, the initial comment stays visible. Now with the added fact that this question/comment has been resolved in its subdiscussion.
@pedroms et al. Can we just use the same terms as slack? Start a thread is much clearer than something something Discussion. It's not immediately obvious to a new user what a 'discussion' means in GitLab terms. Thread is clear though.
I think make resolvable is even worse, but it looks that that's already getting addressed.
Resolving a thread doesn't make much sense to me, esp. not in a first iteration. It's not code review, there's no checking off on things. I'd remove it for the sake of simplicity. If there's need, we can always reconsider.
It's not immediately obvious to a new user what a 'discussion' means in GitLab terms. Thread is clear though.
This is a very good point. To existing users of GitLab, especially those that use merge requests frequently, "discussion" should be clear because its very much part of the MR commenting UI. For issues right now, this is not common and so for users who only use issues (and not MRs) and for new users, "thread" would be a nice term.