From ace615cfa2f91a6bdf4dc0aede12b71da34a5074 Mon Sep 17 00:00:00 2001 From: oppiliappan Date: Thu, 16 Apr 2026 16:26:45 +0100 Subject: [PATCH] wip: blog Signed-off-by: oppiliappan --- blog/posts/review.md | 177 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 blog/posts/review.md diff --git a/blog/posts/review.md b/blog/posts/review.md new file mode 100644 index 00000000..6a0c5e35 --- /dev/null +++ b/blog/posts/review.md @@ -0,0 +1,177 @@ +--- +atroot: true +template: +slug: review +title: revisiting the pull-request interface +subtitle: an attempt at fixing some gripes with the PR UI +date: 2026-04-28 +image: https://assets.tangled.network/blog/hidden-ref.png +authors: + - name: Akshay + email: akshay@tangled.sh + handle: oppi.li +draft: true +--- + +I have a few nits with the pull-request interface on +traditional forges: + +- the diff is not shown up front, it is typically on + separate tab +- comments are rendered inside the diff +- inline comments are attached to a single line + +To redesign the PR page for Tangled, I wanted to address +these nits. As with every interface, some folks may be +acclimatized to one design, and would rather not see it +changed. + +## diffs up front + +Code and review are equally important in code-review. It +would be criminal to put them on separate tabs, but most +forges do: + +
+ + + +
+ +Let's move the diff into the main view, evicting +conversations for now: + +
+ + + +
+ +To deal with the comments now, they *could* be overlaid on the +diff, like GitHub does... + +
+ + + +
+ +... but this makes the code hard to read. Review systems +like Figma and Google docs put the conversations off to the +right. This is especially nice with code review, because you +tend to want to jump around the diff as you author the +comment, or jump around the diff as you read a review: + +
+ + + +
+ +Nowadays, forges include a filetree to the left, so lets add +that in as well: + +
+ + + +
+ +It's definitely *cozy*, so all panels should be collapsible: + +
+ + + +
+ + +## authoring review comments + +When writing review comments, you often want to scroll up +and down through the diff to build an understanding of the +change. If the UI opened up a comment box in place... + +
+ + + +
+ +... it makes it hard to type out the comment *and* scroll +through the diff. + + + +We could put comment authoring off to the side: + +
+ + + +
+ +This not only allows scrolling the diff separately, but also +lets you write comments free-form in text-box, so you could +reference multiple hunks in a single comment. A comment is +not attached to a single location: + + + +## implementation + +First, on the topic of rendering large diffs. Diffs are +inherently super heavy DOM objects. Each diff line needs to +include a: + +- line number +- diff symbol +- red/green/neutral background +- line content + +And this is without syntax-highlighting or character-wise +diffing! Here, I sympathize with GitHub and the likes. The +only way to not crash the page on larger diffs is to just +hide them or use simpler HTML representations. + +As for the collapsible panels, this is easily implemented +using plain CSS! By turning all toggles into checkboxes, we +can use the `:checked` pseudo class: + +```css +#comment-panel { + display: hidden; +} + +#toggle:checked ~ #comment-panel { + display: block; +} +``` + +Finally, to author comments, you can just copy the link to +the line you want to refer to, and paste that into the text +box on the side: + + + +With a bit of JS, this can be automated with a +click-to-comment style interface, which populates the +comment box with the link to that line: + + + +Each comment is simply a free-form text message with links +to code, clicking a link scrolls the page down to the +target: + + + +## notes + +with a few minor rearrangements, i believe we have made +genuine improvements to the standard PR interface offered by +GitHub, GitLab or Forgejo: + +- zero extra clicks to view the diff +- diff and conversation can be read side-by-side +- JS-optional reviewing and commenting -- 2.51.2