comparing 69479b064a34fe6305c356b307b72198571ac8c4 and push-ppzrwtnukqsq on tangled.org/site

+1

.gitignore

··· 2 build/ 3 static/tw.css 4 *.ttf 5 !.gitignore

··· 2 build/ 3 static/tw.css 4 *.ttf 5 + *.woff2 6 !.gitignore

+1 -1

config.yaml

··· 1 preBuild: 2 - tailwindcss -i input.css -o static/tw.css 3 - title: tangled.sh engineering blog 4 # note the trailing slash! 5 url: "https://tangled.sh" 6 description: ""

··· 1 preBuild: 2 - tailwindcss -i input.css -o static/tw.css 3 + title: tangled engineering 4 # note the trailing slash! 5 url: "https://tangled.sh" 6 description: ""

+31 -20

flake.lock

··· 1 { 2 "nodes": { 3 - "ia-fonts-src": { 4 "flake": false, 5 "locked": { 6 - "lastModified": 1686932517, 7 - "narHash": "sha256-2T165nFfCzO65/PIHauJA//S+zug5nUwPcg8NUEydfc=", 8 - "owner": "iaolo", 9 - "repo": "iA-Fonts", 10 - "rev": "f32c04c3058a75d7ce28919ce70fe8800817491b", 11 - "type": "github" 12 }, 13 "original": { 14 - "owner": "iaolo", 15 - "repo": "iA-Fonts", 16 - "type": "github" 17 } 18 }, 19 "nixpkgs": { ··· 48 }, 49 "root": { 50 "inputs": { 51 - "ia-fonts-src": "ia-fonts-src", 52 "nixpkgs": "nixpkgs", 53 "vite": "vite" 54 } ··· 58 "nixpkgs": "nixpkgs_2" 59 }, 60 "locked": { 61 - "lastModified": 1737395755, 62 - "narHash": "sha256-p69EGNDGdCtdKcuu7y8VAC1q2thV5mpEQDs8/N7xliQ=", 63 - "owner": "icyphox", 64 - "repo": "go-vite", 65 - "rev": "589694da6b9c219b6627980ac86d1a6435d0176a", 66 - "type": "github" 67 }, 68 "original": { 69 - "owner": "icyphox", 70 - "repo": "go-vite", 71 - "type": "github" 72 } 73 } 74 },

··· 1 { 2 "nodes": { 3 + "ibm-plex-mono-src": { 4 "flake": false, 5 "locked": { 6 + "lastModified": 1731402384, 7 + "narHash": "sha256-OwUmrPfEehLDz0fl2ChYLK8FQM2p0G1+EMrGsYEq+6g=", 8 + "type": "tarball", 9 + "url": "https://github.com/IBM/plex/releases/download/@ibm/plex-mono@1.1.0/ibm-plex-mono.zip" 10 }, 11 "original": { 12 + "type": "tarball", 13 + "url": "https://github.com/IBM/plex/releases/download/@ibm/plex-mono@1.1.0/ibm-plex-mono.zip" 14 + } 15 + }, 16 + "inter-fonts-src": { 17 + "flake": false, 18 + "locked": { 19 + "lastModified": 1731680160, 20 + "narHash": "sha256-5vdKKvHAeZi6igrfpbOdhZlDX2/5+UvzlnCQV6DdqoQ=", 21 + "type": "tarball", 22 + "url": "https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip" 23 + }, 24 + "original": { 25 + "type": "tarball", 26 + "url": "https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip" 27 } 28 }, 29 "nixpkgs": { ··· 58 }, 59 "root": { 60 "inputs": { 61 + "ibm-plex-mono-src": "ibm-plex-mono-src", 62 + "inter-fonts-src": "inter-fonts-src", 63 "nixpkgs": "nixpkgs", 64 "vite": "vite" 65 } ··· 69 "nixpkgs": "nixpkgs_2" 70 }, 71 "locked": { 72 + "lastModified": 1744745948, 73 + "narHash": "sha256-8Sda70LhLVDXChifA52xdaIyCS5Sr7UB2bN0Qe4v4eY=", 74 + "ref": "refs/heads/master", 75 + "rev": "92c9c9f24b0f0b78c4a81ab2d3490c756813fe71", 76 + "revCount": 89, 77 + "type": "git", 78 + "url": "https://tangled.sh/@icyphox.sh/vite" 79 }, 80 "original": { 81 + "type": "git", 82 + "url": "https://tangled.sh/@icyphox.sh/vite" 83 } 84 } 85 },

+23 -14

flake.nix

··· 3 4 inputs = { 5 nixpkgs.url = "github:nixos/nixpkgs"; 6 - vite.url = "github:icyphox/go-vite"; 7 - ia-fonts-src = { 8 - url = "github:iaolo/iA-Fonts"; 9 flake = false; 10 }; 11 }; ··· 14 { self 15 , nixpkgs 16 , vite 17 - , ia-fonts-src 18 }: 19 let 20 supportedSystems = [ ··· 42 pkgs.tailwindcss 43 ]; 44 shellHook = '' 45 - cp -f ${ia-fonts-src}/"iA Writer Quattro"/Static/*.ttf static/fonts/ 46 - cp -f ${ia-fonts-src}/"iA Writer Mono"/Static/*.ttf static/fonts/ 47 ''; 48 }; 49 } ··· 63 ''}/bin/vite-build"; 64 cwd = ./.; 65 }; 66 - deploy = { 67 - type = "app"; 68 - program = "${pkgs.writeShellScriptBin "s3-sync" '' 69 - #!/usr/bin/env bash 70 - ${vite.packages.${system}.vite}/bin/vite build 71 - ${pkgs.awscli2}/bin/aws s3 sync build s3://site/ --size-only 72 - ''}/bin/s3-sync"; 73 - }; 74 serve = { 75 type = "app"; 76 program = "${pkgs.writeShellScriptBin "vite-serve" '' ··· 87 ${vite.packages.${system}.vite}/bin/vite serve & 88 find pages/ static/ templates/ | ${pkgs.entr}/bin/entr ${vite.packages.${system}.vite}/bin/vite build --drafts 89 ''}/bin/vite-serve"; 90 }; 91 } 92 );

··· 3 4 inputs = { 5 nixpkgs.url = "github:nixos/nixpkgs"; 6 + vite = { 7 + url = "git+https://tangled.sh/@icyphox.sh/vite"; 8 + flake = true; 9 + }; 10 + inter-fonts-src = { 11 + url = "https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip"; 12 + flake = false; 13 + }; 14 + ibm-plex-mono-src = { 15 + url = "https://github.com/IBM/plex/releases/download/%40ibm%2Fplex-mono%401.1.0/ibm-plex-mono.zip"; 16 flake = false; 17 }; 18 }; ··· 21 { self 22 , nixpkgs 23 , vite 24 + , inter-fonts-src 25 + , ibm-plex-mono-src 26 }: 27 let 28 supportedSystems = [ ··· 50 pkgs.tailwindcss 51 ]; 52 shellHook = '' 53 + cp -f ${inter-fonts-src}/web/InterVariable*.woff2 static/fonts/ 54 + cp -f ${inter-fonts-src}/web/InterDisplay*.woff2 static/fonts/ 55 + cp -f ${ibm-plex-mono-src}/fonts/complete/woff2/IBMPlexMono-Regular.woff2 static/fonts/ 56 ''; 57 }; 58 } ··· 72 ''}/bin/vite-build"; 73 cwd = ./.; 74 }; 75 serve = { 76 type = "app"; 77 program = "${pkgs.writeShellScriptBin "vite-serve" '' ··· 88 ${vite.packages.${system}.vite}/bin/vite serve & 89 find pages/ static/ templates/ | ${pkgs.entr}/bin/entr ${vite.packages.${system}.vite}/bin/vite build --drafts 90 ''}/bin/vite-serve"; 91 + }; 92 + deploy = { 93 + type = "app"; 94 + program = "${pkgs.writeShellScriptBin "deploy" '' 95 + #!/usr/bin/env bash 96 + ${vite.packages.${system}.vite}/bin/vite build 97 + ${pkgs.wrangler}/bin/wrangler pages deploy --project-name tangled-blog ./build 98 + ''}/bin/deploy"; 99 }; 100 } 101 );

+51 -104

input.css

··· 2 @tailwind components; 3 @tailwind utilities; 4 @layer base { 5 - @font-face { 6 - font-family: "iA Writer Quattro S"; 7 - src: url("/static/fonts/iAWriterQuattroS-Regular.ttf") 8 - format("truetype"); 9 - font-weight: normal; 10 - font-style: normal; 11 - font-display: swap; 12 - font-feature-settings: 13 - "calt" 1, 14 - "kern" 1; 15 - } 16 - @font-face { 17 - font-family: "iA Writer Quattro S"; 18 - src: url("/static/fonts/iAWriterQuattroS-Bold.ttf") format("truetype"); 19 - font-weight: bold; 20 - font-style: normal; 21 - font-display: swap; 22 - font-feature-settings: 23 - "calt" 1, 24 - "kern" 1; 25 - } 26 - @font-face { 27 - font-family: "iA Writer Quattro S"; 28 - src: url("/static/fonts/iAWriterQuattroS-Italic.ttf") format("truetype"); 29 - font-weight: normal; 30 - font-style: italic; 31 - font-display: swap; 32 - font-feature-settings: 33 - "calt" 1, 34 - "kern" 1; 35 - } 36 - @font-face { 37 - font-family: "iA Writer Quattro S"; 38 - src: url("/static/fonts/iAWriterQuattroS-BoldItalic.ttf") 39 - format("truetype"); 40 - font-weight: bold; 41 - font-style: italic; 42 - font-display: swap; 43 - font-feature-settings: 44 - "calt" 1, 45 - "kern" 1; 46 - } 47 48 - @font-face { 49 - font-family: "iA Writer Mono S"; 50 - src: url("/static/fonts/iAWriterMonoS-Regular.ttf") format("truetype"); 51 - font-weight: normal; 52 - font-style: normal; 53 - font-display: swap; 54 - font-feature-settings: 55 - "calt" 1, 56 - "kern" 1; 57 - } 58 - @font-face { 59 - font-family: "iA Writer Mono S"; 60 - src: url("/static/fonts/iAWriterMonoS-Bold.ttf") format("truetype"); 61 - font-weight: bold; 62 - font-style: normal; 63 - font-display: swap; 64 - font-feature-settings: 65 - "calt" 1, 66 - "kern" 1; 67 - } 68 - @font-face { 69 - font-family: "iA Writer Mono S"; 70 - src: url("/static/fonts/iAWriterMonoS-Italic.ttf") format("truetype"); 71 - font-weight: normal; 72 - font-style: italic; 73 - font-display: swap; 74 - font-feature-settings: 75 - "calt" 1, 76 - "kern" 1; 77 - } 78 - @font-face { 79 - font-family: "iA Writer Mono S"; 80 - src: url("/static/fonts/iAWriterMonoS-BoldItalic.ttf") 81 - format("truetype"); 82 - font-weight: bold; 83 - font-style: italic; 84 - font-display: swap; 85 - font-feature-settings: 86 - "calt" 1, 87 - "kern" 1; 88 - } 89 90 - @font-face { 91 - font-family: "Inter"; 92 - font-style: normal; 93 - font-weight: 400; 94 - font-display: swap; 95 - font-feature-settings: 96 - "calt" 1, 97 - "kern" 1; 98 - } 99 - h1 { 100 @apply text-2xl; 101 - @apply font-sans; 102 @apply text-black; 103 @apply font-bold; 104 } 105 106 ::selection { 107 @apply bg-yellow-400; 108 - @apply text-black; 109 @apply bg-opacity-30; 110 } 111 112 - html { 113 - letter-spacing: -0.01em; 114 - word-spacing: -0.07em; 115 - } 116 - 117 @layer base { 118 a { 119 - @apply no-underline text-black hover:underline hover:text-gray-800; 120 } 121 122 label { 123 - @apply block text-sm text-black; 124 } 125 input { 126 - @apply bg-white border border-black rounded-sm focus:ring-black p-2; 127 } 128 textarea { 129 - @apply bg-white border border-black rounded-sm focus:ring-black p-2; 130 } 131 } 132

··· 2 @tailwind components; 3 @tailwind utilities; 4 @layer base { 5 + @font-face { 6 + font-family: "InterVariable"; 7 + src: url("/static/fonts/InterVariable.woff2") format("woff2"); 8 + font-weight: normal; 9 + font-style: normal; 10 + font-display: swap; 11 + } 12 + 13 + @font-face { 14 + font-family: "InterVariable"; 15 + src: url("/static/fonts/InterVariable-Italic.woff2") format("woff2"); 16 + font-weight: normal; 17 + font-style: italic; 18 + font-display: swap; 19 + } 20 + 21 + @font-face { 22 + font-family: "InterDisplay"; 23 + src: url("/static/fonts/InterDisplay-Regular.woff2") format("woff2"); 24 + font-weight: normal; 25 + font-style: normal; 26 + font-display: swap; 27 + } 28 29 + @font-face { 30 + font-family: "IBMPlexMono"; 31 + src: url("/static/fonts/IBMPlexMono-Regular.woff2") format("woff2"); 32 + font-weight: normal; 33 + font-style: italic; 34 + font-display: swap; 35 + } 36 37 + h1 { 38 @apply text-2xl; 39 @apply text-black; 40 @apply font-bold; 41 } 42 43 ::selection { 44 @apply bg-yellow-400; 45 @apply bg-opacity-30; 46 } 47 48 @layer base { 49 + html { 50 + font-size: 15px; 51 + } 52 + @supports (font-variation-settings: normal) { 53 + html { 54 + font-feature-settings: 'ss01' 1, 'kern' 1, 'liga' 1, 'cv05' 1, 'tnum' 1; 55 + } 56 + } 57 + 58 a { 59 + @apply no-underline text-black hover:underline hover:text-gray-800 dark:text-white dark:hover:text-gray-300; 60 + } 61 + 62 + img { 63 + @apply dark:brightness-75 dark:opacity-90 border border-gray-200 rounded-sm dark:border-gray-700; 64 } 65 66 label { 67 + @apply block mb-2 text-gray-900 text-sm font-bold py-2 uppercase dark:text-gray-100; 68 } 69 input { 70 + @apply bg-white border border-gray-400 rounded-sm focus:ring-black p-3 dark:bg-gray-800 dark:border-gray-600 dark:text-white dark:focus:ring-gray-400; 71 } 72 textarea { 73 + @apply bg-white border border-gray-400 rounded-sm focus:ring-black p-3 dark:bg-gray-800 dark:border-gray-600 dark:text-white dark:focus:ring-gray-400; 74 + } 75 + details summary::-webkit-details-marker { 76 + display: none; 77 } 78 } 79

+21 -13

pages/blog/intro.md

··· 4 slug: intro 5 title: introducing tangled 6 subtitle: a git collaboration platform, built on atproto 7 - date: 2025-03-01 8 - draft: true 9 --- 10 11 ··· 23 24 ![tangled architecture](/static/img/arch.svg) 25 26 - Our addition to this model is the idea of "knots". Knots are 27 - lightweight, headless servers that enable users to host git repositories 28 - with ease. Knots are designed for either single or multi-tenant use 29 - which is perfect for "community" servers. By default, Tangled provides 30 - managed knots where you can host your repositories for free. 31 32 The [App View][appview] at [tangled.sh](https://tangled.sh) acts as a 33 consolidated "view" into the whole network, allowing users to access, ··· 35 completely seamlessly. 36 37 Tangled is still in its infancy, and we're building out several of its 38 - core features as we dogfood it ourselves. We developed these three core 39 - tenets to guide our decisions: 40 41 1. Ownership of data 42 2. Low barrier to entry ··· 45 Collaborating on code isn't easy, and the tools and workflows we use 46 should feel natural and stay out of the way. Tangled's architecture 47 enables common workflows to work as you'd expect, all while remaining 48 - decentralized. 49 50 We believe that atproto has greatly simplfied one of the hardest parts 51 - of social media: having your friends on it. We're rolling out 52 - invite-only access to Tangled -- join us on IRC and we'll get you set 53 - up. 54 55 [pds]: https://atproto.com/guides/glossary#pds-personal-data-server 56 [appview]: https://docs.bsky.app/docs/advanced-guides/federation-architecture#app-views

··· 4 slug: intro 5 title: introducing tangled 6 subtitle: a git collaboration platform, built on atproto 7 + date: 2025-03-02 8 + authors: 9 + - name: Anirudh 10 + email: anirudh@tangled.sh 11 + handle: icyphox.sh 12 --- 13 14 ··· 26 27 ![tangled architecture](/static/img/arch.svg) 28 29 + Our approach to this is the idea of "knots". Knots are lightweight, 30 + headless servers that enable users to host Git repositories with ease. 31 + Knots are designed for either single or multi-tenant use which is 32 + perfect for self-hosting on a Raspberry Pi at home, or larger 33 + "community" servers. By default, Tangled provides managed knots where 34 + you can host your repositories for free. 35 36 The [App View][appview] at [tangled.sh](https://tangled.sh) acts as a 37 consolidated "view" into the whole network, allowing users to access, ··· 39 completely seamlessly. 40 41 Tangled is still in its infancy, and we're building out several of its 42 + core features as we [dogfood it ourselves][dogfood]. We developed these 43 + three tenets to guide our decisions: 44 45 1. Ownership of data 46 2. Low barrier to entry ··· 49 Collaborating on code isn't easy, and the tools and workflows we use 50 should feel natural and stay out of the way. Tangled's architecture 51 enables common workflows to work as you'd expect, all while remaining 52 + decentralized. 53 54 We believe that atproto has greatly simplfied one of the hardest parts 55 + of social media: having your friends on it. Today, we're rolling out 56 + invite-only access to Tangled -- join us on IRC at `#tangled` on 57 + [libera.chat](https://libera.chat) and we'll get you set up. 58 + 59 + **Update**: Tangled is open to public, simply login at 60 + [tangled.sh/login](https://tangled.sh/login)! Have fun! 61 62 [pds]: https://atproto.com/guides/glossary#pds-personal-data-server 63 [appview]: https://docs.bsky.app/docs/advanced-guides/federation-architecture#app-views 64 + [dogfood]: https://tangled.sh/@tangled.sh/core

+188

pages/blog/pulls.md

···

··· 1 + --- 2 + atroot: true 3 + template: 4 + slug: pulls 5 + title: the lifecycle of a pull request 6 + subtitle: we shipped a bunch of PR features recently; here's how we built it 7 + date: 2025-04-16 8 + image: /static/img/hidden-ref.png 9 + authors: 10 + - name: Anirudh 11 + email: anirudh@tangled.sh 12 + handle: icyphox.sh 13 + - name: Akshay 14 + email: akshay@tangled.sh 15 + handle: oppili.bsky.social 16 + draft: false 17 + --- 18 + 19 + We've spent the last couple of weeks building out a pull 20 + request system for Tangled, and today we want to lift the 21 + hood and show you how it works. 22 + 23 + If you're new to Tangled, [read our intro](/intro) for the 24 + full story! 25 + 26 + You have three options to contribute to a repository: 27 + 28 + - Paste a patch on the web UI 29 + - Compare two local branches (you'll see this only if you're a 30 + collaborator on the repo) 31 + - Compare across forks 32 + 33 + Whatever you choose, at the core of every PR is the patch. 34 + First, you write some code. Then, you run `git diff` to 35 + produce a patch and make everyone's lives easier, or push to 36 + a branch, and we generate it ourselves by comparing against 37 + the target. 38 + 39 + ## patch generation 40 + 41 + When you create a PR from a branch, we create a "patch" by 42 + calculating the difference between your branch and the 43 + target branch. Consider this scenario: 44 + 45 + <figure class="max-w-[550px] m-auto flex flex-col items-center justify-center"> 46 + <img class="h-auto max-w-full" src="/static/img/merge-base.png"> 47 + <figcaption class="text-center"><code>A</code> is the merge-base for 48 + <code>feature</code> and <code>main</code>.</figcaption> 49 + </figure> 50 + 51 + Your `feature` branch has advanced 2 commits since you first 52 + branched out, but in the meanwhile, `main` has also advanced 53 + 2 commits. Doing a trivial `git diff feature main` will 54 + produce a confusing patch: 55 + 56 + - the patch will apply the changes from `X` and `Y` 57 + - the patch will **revert** the changes from `B` and `C` 58 + 59 + We obviously do not want the second part! To only show the 60 + changes added by `feature`, we have to identify the 61 + "merge-base": the nearest common ancestor of `feature` and 62 + `main`. 63 + 64 + 65 + In this case, `A` is the nearest common ancestor, and 66 + subsequently, the patch calculated will contain just `X` and 67 + `Y`. 68 + 69 + ### ref comparisons across forks 70 + 71 + The plumbing described above is easy to do across two 72 + branches, but what about forks? And what if they live on 73 + different servers altogether (as they can in Tangled!)? 74 + 75 + Here's the concept: since we already have all the necessary 76 + components to compare two local refs, why not simply 77 + "localize" the remote ref? 78 + 79 + In simpler terms, we instruct Git to fetch the target branch 80 + from the original repository and store it in your fork under 81 + a special name. This approach allows us to compare your 82 + changes against the most current version of the branch 83 + you're trying to contribute to, all while remaining within 84 + your fork. 85 + 86 + <figure class="max-w-[550px] m-auto flex flex-col items-center justify-center"> 87 + <img class="h-auto max-w-full" src="/static/img/hidden-ref.png"> 88 + <figcaption class="text-center">Hidden tracking ref.</figcaption> 89 + </figure> 90 + 91 + We call this a "hidden tracking ref." When you create a pull 92 + request from a fork, we establish a refspec that tracks the 93 + remote branch, which we then use to generate a diff. A 94 + refspec is essentially a rule that tells Git how to map 95 + references between a remote and your local repository during 96 + fetch or push operations. 97 + 98 + For example, if your fork has a feature branch called 99 + `feature-1`, and you want to make a pull request to the 100 + `main` branch of the original repository, we fetch the 101 + remote `main` into a local hidden ref using a refspec like 102 + this: 103 + 104 + ``` 105 + +refs/heads/main:refs/hidden/feature-1/main 106 + ``` 107 + 108 + Since we already have a remote (`origin`, by default) to the 109 + original repository (remember, we cloned it earlier), we can 110 + use `fetch` with this refspec to bring the remote `main` 111 + branch into our local hidden ref. Each pull request gets its 112 + own hidden ref, hence the `refs/hidden/:localRef/:remoteRef` 113 + format. We keep this ref updated whenever you push new 114 + commits to your feature branch, ensuring that comparisons -- 115 + and any potential merge conflicts -- are always based on the 116 + latest state of the target branch. 117 + 118 + And just like earlier, we produce the patch by diffing your 119 + feature branch with the hidden tracking ref. Also, the entire pull 120 + request is stored as [an atproto record][atproto-record] and updated 121 + each time the patch changes. 122 + 123 + [atproto-record]: https://pdsls.dev/at://did:plc:qfpnj4og54vl56wngdriaxug/sh.tangled.repo.pull/3lmwniim2i722 124 + 125 + Neat, now that we have a patch; we can move on the hard 126 + part: code review. 127 + 128 + 129 + ## your patch does the rounds 130 + 131 + Tangled uses a "round-based" review format. Your initial 132 + submission starts "round 0". Once your submission receives 133 + scrutiny, you can address reviews and resubmit your patch. 134 + This resubmission starts "round 1". You keep whittling on 135 + your patch till it is good enough, and eventually merged (or 136 + closed if you are unlucky). 137 + 138 + <figure class="max-w-[700px] m-auto flex flex-col items-center justify-center"> 139 + <img class="h-auto max-w-full" src="/static/img/patch-pr-main.png"> 140 + <figcaption class="text-center">A new pull request with a couple 141 + rounds of reviews.</figcaption> 142 + </figure> 143 + 144 + Rounds are a far superior to standard branch-based 145 + approaches: 146 + 147 + - Submissions are immutable: how many times have your 148 + reviews gone out-of-date because the author pushed commits 149 + _during_ your review? 150 + - Reviews are attached to submissions: at a glance, it is 151 + easy to tell which comment applies to which "version" of 152 + the pull-request 153 + - The author can choose when to resubmit! They can commit as 154 + much as they want to their branch, but a new round begins 155 + when they choose to hit "resubmit" 156 + - It is possible to "interdiff" and observe changes made 157 + across submissions (this is coming very soon to Tangled!) 158 + 159 + This [post by Mitchell 160 + Hashimoto](https://mitchellh.com/writing/github-changesets) 161 + goes into further detail on what can be achieved with 162 + round-based reviews. 163 + 164 + ## future plans 165 + 166 + To close off this post, we wanted to share some of our 167 + future plans for pull requests: 168 + 169 + * `format-patch` support: both for pasting in the UI and 170 + internally. This allows us to show commits in the PR page, 171 + and offer different merge strategies to choose from 172 + (squash, rebase, ...). 173 + 174 + * Gerrit-style `refs/for/main`: we're still hashing out the 175 + details but being able to push commits to a ref to 176 + "auto-create" a PR would be super handy! 177 + 178 + * Change ID support: This will allow us to group changes 179 + together and track them across multiple commits, and to 180 + provide "history" for each change. This works great with [Jujutsu][jj]. 181 + 182 + Join us on [Discord](https://chat.tangled.sh) or 183 + `#tangled` on libera.chat (the two are bridged, so we will 184 + never miss a message!). We are always available to help 185 + setup knots, listen to feedback on features, or even 186 + shepherd contributions! 187 + 188 + [jj]: https://jj-vcs.github.io/jj/latest/

+364

pages/blog/stacking.md

···

··· 1 + --- 2 + atroot: true 3 + template: 4 + slug: stacking 5 + title: jujutsu-style code review 6 + subtitle: we now support jujutsu style "interdiff" code-review! 7 + date: 2025-06-02 8 + image: /static/img/hidden-ref.png 9 + authors: 10 + - name: Akshay 11 + email: akshay@tangled.sh 12 + handle: oppi.li 13 + draft: true 14 + --- 15 + 16 + Jujutsu is built around structuring your work into 17 + meaningful commits. Naturally, during code-review, you'd 18 + expect reviewers to be able to comment on individual 19 + commits, and also see the evolution of a commit over time, 20 + as reviews are addressed. We set out to natively support 21 + this model of code-review on Tangled. 22 + 23 + If you're new to Tangled, [read our intro](/intro) for more 24 + about the project. 25 + 26 + For starters, I would like to contrast the two schools of 27 + code-review, the "diff-soup" model and the interdiff model. 28 + 29 + ## the diff soup model 30 + 31 + When you create a PR on traditional code-forges (GitHub 32 + specifically), the UX implicitly encourages you to address 33 + your code review by *adding commits* on top of your original 34 + set of changes: 35 + 36 + - GitHub's "Apply Suggestion" button directly commits the 37 + suggestion into your PR 38 + - GitHub only shows you the diff of all files at once by 39 + default 40 + - It is difficult to know what changed across force-pushes 41 + 42 + Consider a hypothetical PR that adds 3 commits: 43 + 44 + ``` 45 + [c] implement new feature across the board (HEAD) 46 + | 47 + [b] introduce new feature 48 + | 49 + [a] some small refactor 50 + ``` 51 + 52 + And when only *newly added commits* are easy to review, this 53 + is what ends up happening: 54 + 55 + ``` 56 + [f] formatting & linting (HEAD) 57 + | 58 + [e] update name of new feature 59 + | 60 + [d] fix bug in refactor 61 + | 62 + [c] implement new feature across the board 63 + | 64 + [b] introduce new feature 65 + | 66 + [a] some small refactor 67 + ``` 68 + 69 + It is impossible to tell what addresses what at a glance, 70 + there is an implicit relation between each change: 71 + 72 + ``` 73 + [f] formatting & linting 74 + | 75 + [e] update name of new feature -------------. 76 + | | 77 + [d] fix bug in refactor -----------. | 78 + | | | 79 + [c] implement new feature across the board | 80 + | | | 81 + [b] introduce new feature <-----------------' 82 + | | 83 + [a] some small refactor <----------' 84 + ``` 85 + 86 + This has the downside of clobbering the output of `git 87 + blame` (if there is a bug in the new feature, you will first 88 + land on `e`, and upon digging further, you will land on 89 + `b`). 90 + 91 + 92 + ## the interdiff model 93 + 94 + With jujutsu however, you have the tools at hand to 95 + fearlessly edit, split, squash and rework old commits (you 96 + could do this with git if you are familiar with fixup 97 + commits or interactive rebasing). 98 + 99 + Lets try that again: 100 + 101 + ``` 102 + [c] implement new feature across the board (HEAD) 103 + | 104 + [b] introduce new feature 105 + | 106 + [a] some small refactor 107 + ``` 108 + 109 + To fix the bug in the refactor: 110 + 111 + ``` 112 + $ jj edit a 113 + Working copy (@) now at: [a] some small refactor 114 + 115 + $ # hack hack hack 116 + 117 + $ jj log -r a:: 118 + Rebased 2 descendant commits onto updated working copy 119 + [c] implement new feature across the board (HEAD) 120 + | 121 + [b] introduce new feature 122 + | 123 + [a] some small refactor 124 + ``` 125 + 126 + This is the most important part: 127 + 128 + ``` 129 + Rebased 2 descendant commits onto updated working copy 130 + ``` 131 + 132 + Jujutsu automatically rebases the descendants without having 133 + to lift a finger. Brilliant! You can repeat the same 134 + exercise for all review comments, and effectively, your 135 + PR will have evolved like so: 136 + 137 + ``` 138 + a -> b -> c 139 + | | | 140 + v v v 141 + a' -> b' -> c' 142 + ``` 143 + 144 + ## the catch 145 + 146 + If you use `git rebase`, you will know that it modifies 147 + history and therefore changes the commit SHA. How then, 148 + should one tell the difference between the "old" and "new" 149 + state of affairs? 150 + 151 + Tools like `git-range-diff` make use of a variety of 152 + text-based heuristics to roughly match `a` to `a'` and `b` 153 + to `b'` etc. 154 + 155 + Jujutsu however, works around this by assigning stable 156 + "change id"s to each change (which internally point to a git 157 + commit, if you use the git backing). If you edit an old 158 + commit, its SHA changes, but its change-id remains the same. 159 + 160 + And this is the essence of our new stacked PRs feature! 161 + 162 + ## interdiff code review on tangled 163 + 164 + To really explain how this works, lets start with a [new 165 + codebase](https://tangled.sh/@oppi.li/stacking-demo/): 166 + 167 + ``` 168 + $ jj git init --colocate 169 + 170 + # -- initialize codebase -- 171 + 172 + $ jj log 173 + @ n set: introduce Set type main HEAD 1h 174 + ``` 175 + 176 + I have kicked things off by creating a new go module that 177 + adds a `HashSet` data structure. My first changeset 178 + introduces some basic set operations: 179 + 180 + ``` 181 + $ jj log 182 + @ so set: introduce set difference HEAD 183 + ├ sq set: introduce set intersection 184 + ├ mk set: introduce set union 185 + ├ my set: introduce basic set operations 186 + ~ 187 + 188 + $ jj git push -c @ 189 + Changes to push to origin: 190 + Add bookmark push-soqmukrvport to fc06362295bd 191 + ``` 192 + 193 + On the New Pull Request page, when submitting this branch 194 + for review, select "Submit as stacked PRs": 195 + 196 + <figure class="max-w-[550px] m-auto flex flex-col items-center justify-center"> 197 + <a href="static/img/submit_stacked.jpeg"> 198 + <img class="my-1 h-auto max-w-full" src="static/img/submit_stacked.jpeg"> 199 + </a> 200 + <figcaption class="text-center">Submitting Stacked PRs</figcaption> 201 + </figure> 202 + 203 + This submits each change as an individual pull request: 204 + 205 + <figure class="max-w-[550px] m-auto flex flex-col items-center justify-center"> 206 + <a href="static/img/top_of_stack.jpeg"> 207 + <img class="my-1 h-auto max-w-full" src="static/img/top_of_stack.jpeg"> 208 + </a> 209 + <figcaption class="text-center">The "stack" attachment is similar to Gerrit's relation chain</figcaption> 210 + </figure> 211 + 212 + After a while, I receive a couple of review comments, but 213 + not on my entire submission, but rather, on each *individual 214 + change*. Additionally, the reviewer is happy with my first 215 + change, and has gone ahead and merged that: 216 + 217 + <div class="flex justify-center items-start gap-2"> 218 + <figure class="w-1/3 m-0 flex flex-col items-center"> 219 + <a href="static/img/basic_merged.jpeg"> 220 + <img class="my-1 w-full h-auto cursor-pointer" src="static/img/basic_merged.jpeg" alt="The first change has been merged"> 221 + </a> 222 + <figcaption class="text-center">The first change has been merged</figcaption> 223 + </figure> 224 + 225 + <figure class="w-1/3 m-0 flex flex-col items-center"> 226 + <a href="static/img/review_union.jpeg"> 227 + <img class="my-1 w-full h-auto cursor-pointer" src="static/img/review_union.jpeg" alt="A review on the set union implementation"> 228 + </a> 229 + <figcaption class="text-center">A review on the set union implementation</figcaption> 230 + </figure> 231 + 232 + <figure class="w-1/3 m-0 flex flex-col items-center"> 233 + <a href="static/img/review_difference.jpeg"> 234 + <img class="my-1 w-full h-auto cursor-pointer" src="static/img/review_difference.jpeg" alt="A review on the set difference implementation"> 235 + </a> 236 + <figcaption class="text-center">A review on the set difference implementation</figcaption> 237 + </figure> 238 + </div> 239 + 240 + Let us address the first review: 241 + 242 + > can you use the new `maps.Copy` api here? 243 + 244 + ``` 245 + $ jj log 246 + @ so set: introduce set difference push-soqmukrvport 247 + ├ sq set: introduce set intersection 248 + ├ mk set: introduce set union 249 + ├ my set: introduce basic set operations 250 + ~ 251 + 252 + # lets edit the implementation of `Union` 253 + $ jj edit mk 254 + 255 + # hack, hack, hack 256 + 257 + $ jj log 258 + Rebased 2 descendant commits onto updated working copy 259 + ├ so set: introduce set difference push-soqmukrvport* 260 + ├ sq set: introduce set intersection 261 + @ mk set: introduce set union 262 + ├ my set: introduce basic set operations 263 + ~ 264 + ``` 265 + 266 + Next, let us address the bug: 267 + 268 + > there is a logic bug here, the condition should be negated. 269 + 270 + ``` 271 + # lets edit the implementation of `Difference` 272 + $ jj edit so 273 + 274 + # hack, hack, hack 275 + 276 + $ jj log 277 + @ so set: introduce set difference push-soqmukrvport* 278 + ├ sq set: introduce set intersection 279 + ├ mk set: introduce set union 280 + ├ my set: introduce basic set operations 281 + ~ 282 + ``` 283 + 284 + We are done addressing reviews, let us push our code: 285 + ``` 286 + $ jj git push 287 + Changes to push to origin: 288 + Move sideways bookmark push-soqmukrvport from fc06362295bd to dfe2750f6d40 289 + ``` 290 + 291 + Upon resubmitting the PR for review: 292 + 293 + <div class="flex justify-center items-start gap-2"> 294 + <figure class="w-1/2 m-0 flex flex-col items-center"> 295 + <a href="static/img/round_2_union.jpeg"> 296 + <img class="my-1 w-full h-auto" src="static/img/round_2_union.jpeg" alt="PR #2 advances to the next round"> 297 + </a> 298 + <figcaption class="text-center">PR #2 advances to the next round</figcaption> 299 + </figure> 300 + 301 + <figure class="w-1/2 m-0 flex flex-col items-center"> 302 + <a href="static/img/round_2_difference.jpeg"> 303 + <img class="my-1 w-full h-auto" src="static/img/round_2_difference.jpeg" alt="PR #4 advances to the next round"> 304 + </a> 305 + <figcaption class="text-center">PR #4 advances to the next round</figcaption> 306 + </figure> 307 + </div> 308 + 309 + Of note here are a few things: 310 + 311 + - The initial submission is still visible under `round #0` 312 + - By resubmitting, the round has simply advanced to `round 313 + #1` 314 + - There is a helpful "interdiff" button to look at the 315 + difference between the two submissions 316 + 317 + The individual diffs are still available, but most 318 + importantly, the reviewer can view the *evolution* of a 319 + change by hitting the interdiff button: 320 + 321 + <div class="flex justify-center items-start gap-2"> 322 + <figure class="w-1/2 m-0 flex flex-col items-center"> 323 + <a href="static/img/diff_1_difference.jpeg"> 324 + <img class="my-1 w-full h-auto" src="static/img/diff_1_difference.jpeg" alt="Diff from round #0"> 325 + </a> 326 + <figcaption class="text-center">Diff from round #0</figcaption> 327 + </figure> 328 + 329 + <figure class="w-1/2 m-0 flex flex-col items-center"> 330 + <a href="static/img/diff_2_difference.jpeg"> 331 + <img class="my-1 w-full h-auto" src="static/img/diff_2_difference.jpeg" alt="Diff from round #1"> 332 + </a> 333 + <figcaption class="text-center">Diff from round #1</figcaption> 334 + </figure> 335 + </div> 336 + 337 + <figure class="max-w-[550px] m-auto flex flex-col items-center justify-center"> 338 + <a href="static/img/interdiff_difference.jpeg"> 339 + <img class="my-1 w-full h-auto" src="static/img/interdiff_difference.jpeg" alt="Interdiff between round #0 and #1"> 340 + </a> 341 + <figcaption class="text-center">Interdiff between round #1 and #0</figcaption> 342 + </figure> 343 + 344 + Indeed, the logic bug has been addressed! 345 + 346 + ## start stacking today 347 + 348 + If you are a jujutsu user, you can enable this flag on more 349 + recent versions of jujutsu: 350 + 351 + ``` 352 + λ jj --version 353 + jj 0.29.0-8c7ca30074767257d75e3842581b61e764d022cf 354 + 355 + # -- in your config.toml file -- 356 + [git] 357 + write-change-id-header = true 358 + ``` 359 + 360 + This feature writes `change-id` headers directly into the 361 + git commit object, and is visible to code-forges upon push, 362 + and allows you to stack your PRs on Tangled. 363 + 364 +

static/img/basic_merged.jpeg