repos / git-pr

commit

5ee4d60

parent

aa526fc

author

Eric Bower

date

2024-04-29 10:18:20 -0400 EDT

sauce

  1@@ -1,26 +1,88 @@
  2+# rfc: `pico/git` a self-hosted git server
  3+
  4+The goal is not to create another code forge here. The goal is to create a very
  5+simple self-hosted git solution with the ability to collaborate with external
  6+contributors. All the code owner needs to setup a running git server:
  7+
  8+- A single golang binary
  9+- sqlite to store patch requests and other repo metadata
 10+
 11+All an external contributor needs is:
 12+
 13+- An SSH keypair
 14+- An SSH client
 15+
 16 # patch requests
 17 
 18-## format-patch
 19+Email is great as a decentralized system to send and receive changes (patchsets)
 20+to a git repo. However, setting up your email client and understanding the
 21+potential gotchas during that flow cannot be understated. Further, because we
 22+are leveraging the email protocol for communication and collaboration, we are
 23+limited by its feature-set. In particular, it is not possible to make edits to
 24+emails, so if there are typos or the contributor forgot to include some code or
 25+a line in the cover letter, there is a lot of back-and-forth noise to make those
 26+corrections.
 27+
 28+Further, when a contributor provides a patchset and receives feedback, the
 29+contributor must submit another patchset via email. These are completely
 30+separate and the only way to correlate them is via naming convention (e.g.
 31+[PATCH] xxx v2). Now when reviewing patchsets submitted to a project, the user
 32+must search for all versions of that particular patchset. These are separate
 33+conversations with potentially very different patches spanning across the time
 34+of a project. Maybe that's ok, but people are very used to a PR containing all
 35+changes and reviews across time, and I think it makes a lot of sense to have a
 36+single view of all conversations related to a change request.
 37+
 38+Another issue with the email workflow is knowing how to properly reply to a
 39+patchset. There is a lot of education on "doing patchsets right via email."
 40+
 41+Github pull requests are easy to use, easy to edit, and easy to manage. The
 42+downside is it forces the user to be inside their website to perform reviews.
 43+For quick changes, this is great, but when you start reading code within a web
 44+browser, there are quite a few downsides. At a certain point, it makes more
 45+sense to review code inside your local development environment, IDE, etc.
 46+Further, self-hosted solutions that mimick a pull request require a lot of
 47+infrastructure in order to manage it. For example, before an external user who
 48+wants to contribute to a repo, they first need to create an account and then
 49+login. This adds quite a bit of friction for a self-hosted solution, not only
 50+for an external contributor, but also for the code owner who has to provision
 51+the infra.
 52+
 53+Instead, I want to create a self-hosted git "server" that can handle sending and
 54+receiving patches without the cumbersome nature of setting up email or the
 55+limitations imposed by the email protocol. Further, I want the primary workflow
 56+to surround the local development environment. Github is bringing the IDE to the
 57+browser in order to support their workflow, I want to bring the workflow to the
 58+local dev environment.
 59+
 60+I see this as a hybrid between the github workflow of a pull request and sending
 61+and receiving patches over email.
 62+
 63+The basic idea is to leverage an SSH app to handle most of the interaction
 64+between contributor and owner of a project. Everything can be done completely
 65+within the terminal, in a way that is ergonomic and fully featured.
 66+
 67+## format-patch workflow
 68 
 69 ```bash
 70-# Owner hosts repo `noice.git` on pico/git
 71+# Owner hosts repo `noice.git` using pico/git
 72 
 73-# User clones repo
 74+# Contributor clones repo
 75 git clone git.sh:/noice.git
 76 
 77-# User wants to make a change
 78-# User makes changes via commits
 79+# Contributor wants to make a change
 80+# Contributor makes changes via commits
 81 git add -A && git commit -m "fix: some bugs"
 82 
 83-# User runs:
 84+# Contributor runs:
 85 git format-patch --stdout | ssh git.sh pr noice
 86-# (-or-) User runs 
 87+# (-or-) Contributor runs 
 88 git format-patch && rsync *.patch git.sh:/noice/
 89 # > Patch Request has been created (ID: noice/1)
 90 
 91-# User can copy down patch request metadata:
 92+# Contributor can copy down patch request metadata:
 93 rsync git.sh:/noice/pr_1.md .
 94-# User edits patch request metadata, then runs:
 95+# Contributor edits patch request metadata, then runs:
 96 rsync pr_1.md git.sh:/noice/
 97 
 98 # Owner can checkout patch:
 99@@ -36,12 +98,36 @@ ssh git.sh pr noice/1 --close
100 # (-maybe-) Owner can merge a pr:
101 ssh git.sh pr noice/1 --squash-n-merge
102 
103-# User can checkout reviews
104+# Contributor can checkout reviews
105 ssh git.sh pr noice/1 | git am -3
106 
107+# Contributor/Owner could also submit a one-off comment:
108+rsync my_comment.md git.sh:/noice/1
109+# (-or-)
110+cat my_comment.md | git.sh comment noice/1
111+
112 # rinse and repeat
113 ```
114 
115+## branch workflow
116+
117+It's definitely possible for us to figure out a way to let the contributor
118+simply push a branch and create a patch request automatically, but there are
119+some rough edges to figure out there in order for it to work well.
120+
121+# web interface
122+
123+The other idea is to make the git web viewer completely static. Whenever an
124+owner pushes code, we generate all the static assets for that branch. We already
125+have a working prototype [pgit](https://github.com/picosh/pgit) that mostly
126+works. Further, any patch request that gets submitted would also be statically
127+generated. If we don't have a web portal with authentication and the ability to
128+manage a repo / patch request inside the web viewer, then a static site becomes
129+possible. This makes the web component of a git server much simpler, since it is
130+just static assets. All we need to do is install a git hook that properly
131+generates the static assets. For patch requests, everything comes through our
132+SSH app so we can generate the assets when those commands are being run.
133+
134 # research
135 
136 - https://git-scm.com/docs/git-format-patch