forked from
tangled.org/core
Monorepo for Tangled
wip: blog
Signed-off-by: oppiliappan <me@oppi.li>
+146
-2
+144
blog/posts/review.md
+144
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-16
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
20
+
- comments are rendered inline, making it hard to navigate
21
+
code and read reviews simultaneously
22
+
- in GitHub's case, diffs are rendered dynamically with
23
+
JS, which breaks Ctrl+F often
24
+
- inline review comments cannot refer to multiple locations,
25
+
they are fixed to a single line
26
+
27
+
To redesign the PR page for Tangled, I wanted to address
28
+
these nits. As with every interface, some folks may be
29
+
acclimatized to one design, and would rather not see it
30
+
changed.
31
+
32
+
## diffs up front
33
+
34
+
Code and review are equally important in code-review. It
35
+
would be criminal to put them on separate tabs. Lets move
36
+
the diff into the main view, evicting conversations for now:
37
+
38
+
<!-- image of inlined diff -->
39
+
40
+
The comments could be overlaid on the diff, like GitHub
41
+
does...
42
+
43
+
<!-- image of overlaid comments -->
44
+
45
+
... but this makes the code hard to read. Review systems
46
+
like Figma and Google docs put the conversations off to the
47
+
right. This is especially nice with code review, because you
48
+
tend to want to jump around the diff as you author the
49
+
comment, or jump around the diff as you read a review:
50
+
51
+
52
+
<!-- image of comment panel -->
53
+
54
+
Nowadays, forges include a filetree to the left, so lets add
55
+
that in as well:
56
+
57
+
<!-- image of file tree panel -->
58
+
59
+
Its definitely *cozy*, so all panels should be collapsible:
60
+
61
+
<!-- image of comment panel collapsed -->
62
+
63
+
## authoring review comments
64
+
65
+
When writing review comments, you often want to scroll up
66
+
and down through the diff to build an understanding of the
67
+
change. If the UI opened up a comment box in place...
68
+
69
+
70
+
<!-- inplace comment box -->
71
+
72
+
... it makes it hard to type out the comment *and* scroll
73
+
through the diff.
74
+
75
+
<!-- animate this? -->
76
+
77
+
We could put commit authoring off to the side:
78
+
79
+
<!-- image of side panel commenting -->
80
+
81
+
This not only allows scrolling the diff separately, but also
82
+
lets you write comments free-form in text-box, so you could
83
+
reference multiple hunks in a single comment. A comment is
84
+
not attached to a single location:
85
+
86
+
<!-- reference multiple hunks -->
87
+
88
+
## implementation
89
+
90
+
First, on the topic of rendering large diffs. Diffs are
91
+
inherently super heavy DOM objects. Each diff line needs to
92
+
include a:
93
+
94
+
- line number
95
+
- diff symbol
96
+
- red/green/neutral background
97
+
- line content
98
+
99
+
And this is without syntax-highlighting or character-wise
100
+
diffing! Here, I sympathize with GitHub and the likes. The
101
+
only way to not crash the page on larger diffs is to just
102
+
hide them or use simpler HTML representations.
103
+
104
+
As for the collapsible panels, this is easily implemented
105
+
using plain CSS! By turning all toggles into checkboxes, we
106
+
can use the `:checked` pseudo class:
107
+
108
+
```css
109
+
#comment-panel {
110
+
display: hidden;
111
+
}
112
+
113
+
#toggle:checked ~ #comment-panel {
114
+
display: block;
115
+
}
116
+
```
117
+
118
+
Finally, to author comments, you can just copy the link to
119
+
the line you want to refer to, and paste that into the text
120
+
box on the side:
121
+
122
+
<!-- paste link into comment box -->
123
+
124
+
With a bit of JS, this can be automated with a
125
+
click-to-comment style interface, which populates the
126
+
comment box with the link to that line:
127
+
128
+
<!-- show click-to-comment video -->
129
+
130
+
Each comment is simply a free-form text message with links
131
+
to code, clicking a link scrolls the page down to the
132
+
target:
133
+
134
+
<!-- show clicking link video -->
135
+
136
+
## notes
137
+
138
+
with a few minor rearrangements, i believe we have made
139
+
genuine improvements to the standard PR interface offered by
140
+
GitHub, GitLab or Forgejo:
141
+
142
+
- zero extra clicks to view the diff
143
+
- diff and conversation can be read side-by-side
144
+
- JS-optional reviewing and commenting
+2
-2
flake.lock
+2
-2
flake.lock
···
120
120
"lastModified": 1731402384,
121
121
"narHash": "sha256-OwUmrPfEehLDz0fl2ChYLK8FQM2p0G1+EMrGsYEq+6g=",
122
122
"type": "tarball",
123
-
"url": "https://github.com/IBM/plex/releases/download/@ibm/plex-mono@1.1.0/ibm-plex-mono.zip"
123
+
"url": "https://github.com/IBM/plex/releases/download/@ibm%2Fplex-mono@1.1.0/ibm-plex-mono.zip"
124
124
},
125
125
"original": {
126
126
"type": "tarball",
127
-
"url": "https://github.com/IBM/plex/releases/download/@ibm/plex-mono@1.1.0/ibm-plex-mono.zip"
127
+
"url": "https://github.com/IBM/plex/releases/download/@ibm%2Fplex-mono@1.1.0/ibm-plex-mono.zip"
128
128
}
129
129
},
130
130
"indigo": {