[usability] In Pull Request view, commenting on changed lines is confusing

[sliedes]

Description

Related, but distinct: #4898 (difference: I'd still want the comments to go to the Pull Request, not the commit, and I'd view this as purely a UI issue.)

As a new user to Gitea, but familiar with Gitlab and Github, this is something that confused me at first. I'll use an arbitrarily chosen Pull Request from gitea.com as an example: https://gitea.com/gitea/act_runner/pulls/69

To be sure, the way it is implemented is logical from a "how the system is designed" point of view, but I found myself first struggling with how to comment on changed lines.

In the Pull Request view, we see three tabs: Conversation, Commits and Files Changed.

At least for me, the natural first approach is to look at the individual commits in the pull request to get a high level overview of the author's intent and not delve immediately into the diff of the whole. This is perhaps reinforced by having the Commits tab before the Files Changed tab. So I click on the Commits tab to see what commits there are.

Now I look into an individual commit by clicking on the SHA1 of one of the commits, getting into this view:

https://gitea.com/gitea/act_runner/commit/96ce0b83d77ff71b026c3838dd09f4920a1a0b7d

Now, obviously, I am viewing a commit. From my mental perspective, though, I am still viewing the code changes of the pull request. I hovered over one of the lines, wanting to comment it. Because I had no previous experience on Gitea's "comment on PR changed lines" feature, I was left wondering if this is a feature Gitea supports at all. Only after reading #4898 I realized that Gitea does support comments on changed lines, and then it still took some figuring out how to do it.

I don't have a clear answer here about what exactly I would like to see, but I have a few suggestions. Essentially, they would involve modifying the UI so that what is shown, in some mental sense, is a "commit view inside a pull request", not a commit in isolation. For example, add an extra parameter to the commit view linking it to a pull request, like commit/96ce0b83d77ff71b026c3838dd09f4920a1a0b7d&pull_request=69. Allow commenting on the lines of the commit in that view, attaching the comments to the pull request. Also show the pull request code line comments on this view. I realize this may entail making some changes to the data included in a pull request code line comment, since commits may make cumulative changes. I don't know if the comments then should be attached "to a single commit in a pull request" to be less confusing. Perhaps?

In Github, this works pretty intuitively. See for example this: 9bb0bbb . Perhaps just take a deep look at what Github does here?

Screenshots

(see screenshots interspersed with description)

Gitea Version

1.20.0+dev-171-gb2c1c17f3

Can you reproduce the bug on the Gitea demo site?

Yes

Operating System

Linux

Browser Version

Firefox 110.0.1

[gempir]

Is this not just comments on commits you want? Because that's exactly what Github does.

Related: #4898

[sliedes]

Actually, I'm not sure. I didn't look quite at how GitHub does it. I read the discussion in #4898, and the idea that comments should be tied to a pull request did seem kind of sensible to me, and the GitHub url that you get when you click s commit in PR view contains both the pull request number and the commit hash, so I assumed they will still be tied to a PR. It may be that I misunderstood what comments on commits are in GitHub. Do they have an existence separate of the PR?

I think one way of implementing this, admittedly not very beautiful, would be to just add a comment on the PR that links to the line in the commit and contains the comment text.

Even more than that, my point is that the UI is confusing. While not ideal, I think even just a note in the commit view saying that you can add comments in the Files Changed view would help alleviate this confusion.