Monorepo for Tangled
tangled.org
wip: blog
Signed-off-by: oppiliappan <me@oppi.li>
+177
+177
blog/posts/review.md
+177
blog/posts/review.md
···
1
+
---
2
+
atroot: true
3
+
template:
4
+
slug: review
5
+
title: revisiting the pull-request interface
6
+
subtitle: an attempt at fixing some gripes with the PR UI
7
+
date: 2026-04-28
8
+
image: https://assets.tangled.network/blog/hidden-ref.png
9
+
authors:
10
+
- name: Akshay
11
+
email: akshay@tangled.sh
12
+
handle: oppi.li
13
+
draft: true
14
+
---
15
+
16
+
I have a few nits with the pull-request interface on
17
+
traditional forges:
18
+
19
+
- the diff is not shown up front, it is typically on
20
+
separate tab
21
+
- comments are rendered inside the diff
22
+
- inline comments are attached to a single line
23
+
24
+
To redesign the PR page for Tangled, I wanted to address
25
+
these nits. As with every interface, some folks may be
26
+
acclimatized to one design, and would rather not see it
27
+
changed.
28
+
29
+
## diffs up front
30
+
31
+
Code and review are equally important in code-review. It
32
+
would be criminal to put them on separate tabs, but most
33
+
forges do:
34
+
35
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
36
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Separate%20tabs.png">
37
+
<img class="my-1 h-auto max-w-full" src="https://assets.tangled.network/blog/pr-review-ui/Separate%20tabs.png">
38
+
</a>
39
+
</figure>
40
+
41
+
Let's move the diff into the main view, evicting
42
+
conversations for now:
43
+
44
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
45
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Diff%20inline.png">
46
+
<img class="my-1 h-auto max-w-full" src="https://assets.tangled.network/blog/pr-review-ui/Diff%20inline.png">
47
+
</a>
48
+
</figure>
49
+
50
+
To deal with the comments now, they *could* be overlaid on the
51
+
diff, like GitHub does...
52
+
53
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
54
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Overlaid%20comments.png">
55
+
<img class="my-1 h-auto max-w-full" src="https://assets.tangled.network/blog/pr-review-ui/Overlaid%20comments.png">
56
+
</a>
57
+
</figure>
58
+
59
+
... but this makes the code hard to read. Review systems
60
+
like Figma and Google docs put the conversations off to the
61
+
right. This is especially nice with code review, because you
62
+
tend to want to jump around the diff as you author the
63
+
comment, or jump around the diff as you read a review:
64
+
65
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
66
+
<a href="https://assets.tangled.network/blog/pr-review-ui/More%20convos%20inline.png">
67
+
<img class="my-1 h-auto max-w-full" src="https://assets.tangled.network/blog/pr-review-ui/More%20convos%20inline.png">
68
+
</a>
69
+
</figure>
70
+
71
+
Nowadays, forges include a filetree to the left, so lets add
72
+
that in as well:
73
+
74
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
75
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Add%20file%20tree.png">
76
+
<img class="my-1 h-auto max-w-full" src="https://assets.tangled.network/blog/pr-review-ui/Add%20file%20tree.png">
77
+
</a>
78
+
</figure>
79
+
80
+
It's definitely *cozy*, so all panels should be collapsible:
81
+
82
+
<figure class="max-w-[550px] m-auto flex flex-col items-center justify-center">
83
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Convos%20can%20be%20collapsible.png">
84
+
<img class="my-1 h-auto max-w-full border-none" src="https://assets.tangled.network/blog/pr-review-ui/Convos%20can%20be%20collapsible.png">
85
+
</a>
86
+
</figure>
87
+
88
+
89
+
## authoring review comments
90
+
91
+
When writing review comments, you often want to scroll up
92
+
and down through the diff to build an understanding of the
93
+
change. If the UI opened up a comment box in place...
94
+
95
+
<figure class="max-w-full m-auto flex flex-col items-center justify-center">
96
+
<a href="https://assets.tangled.network/blog/pr-review-ui/In-place%20comment%20authoring%20is%20a%20struggle.png">
97
+
<img class="my-1 h-auto max-w-full border-none" src="https://assets.tangled.network/blog/pr-review-ui/In-place%20comment%20authoring%20is%20a%20struggle.png">
98
+
</a>
99
+
</figure>
100
+
101
+
... it makes it hard to type out the comment *and* scroll
102
+
through the diff.
103
+
104
+
<!-- animate this? -->
105
+
106
+
We could put comment authoring off to the side:
107
+
108
+
<figure class="max-w-full m-auto flex flex-col items-center justify-center">
109
+
<a href="https://assets.tangled.network/blog/pr-review-ui/Conversation%20scrolls%20separately%20from%20diff.png">
110
+
<img class="my-1 h-auto max-w-full border-none" src="https://assets.tangled.network/blog/pr-review-ui/Conversation%20scrolls%20separately%20from%20diff.png">
111
+
</a>
112
+
</figure>
113
+
114
+
This not only allows scrolling the diff separately, but also
115
+
lets you write comments free-form in text-box, so you could
116
+
reference multiple hunks in a single comment. A comment is
117
+
not attached to a single location:
118
+
119
+
<!-- reference multiple hunks -->
120
+
121
+
## implementation
122
+
123
+
First, on the topic of rendering large diffs. Diffs are
124
+
inherently super heavy DOM objects. Each diff line needs to
125
+
include a:
126
+
127
+
- line number
128
+
- diff symbol
129
+
- red/green/neutral background
130
+
- line content
131
+
132
+
And this is without syntax-highlighting or character-wise
133
+
diffing! Here, I sympathize with GitHub and the likes. The
134
+
only way to not crash the page on larger diffs is to just
135
+
hide them or use simpler HTML representations.
136
+
137
+
As for the collapsible panels, this is easily implemented
138
+
using plain CSS! By turning all toggles into checkboxes, we
139
+
can use the `:checked` pseudo class:
140
+
141
+
```css
142
+
#comment-panel {
143
+
display: hidden;
144
+
}
145
+
146
+
#toggle:checked ~ #comment-panel {
147
+
display: block;
148
+
}
149
+
```
150
+
151
+
Finally, to author comments, you can just copy the link to
152
+
the line you want to refer to, and paste that into the text
153
+
box on the side:
154
+
155
+
<!-- paste link into comment box -->
156
+
157
+
With a bit of JS, this can be automated with a
158
+
click-to-comment style interface, which populates the
159
+
comment box with the link to that line:
160
+
161
+
<!-- show click-to-comment video -->
162
+
163
+
Each comment is simply a free-form text message with links
164
+
to code, clicking a link scrolls the page down to the
165
+
target:
166
+
167
+
<!-- show clicking link video -->
168
+
169
+
## notes
170
+
171
+
with a few minor rearrangements, i believe we have made
172
+
genuine improvements to the standard PR interface offered by
173
+
GitHub, GitLab or Forgejo:
174
+
175
+
- zero extra clicks to view the diff
176
+
- diff and conversation can be read side-by-side
177
+
- JS-optional reviewing and commenting