repos / git-pr

commit

69a42ed

parent

6920206

author

Eric Bower

date

2024-05-21 14:01:06 -0400 EDT

docs: readme

  1@@ -1,4 +1,14 @@
  2-# rfc: `pico/git` a self-hosted git server
  3+# `pico/git-pr` a self-hosted git collaboration server
  4+
  5+We are trying to build the simplest git collaboration tool. The goal is to make
  6+self-hosting a git server as simple as running an SSH server and hosting static
  7+web assets -- all without sacrificing external collaborators.
  8+
  9+> `git format-patch` isn't the problem and pull requests aren't the solution.
 10+
 11+We are combining mailing list and pull request workflows. In order to build the
 12+simplest collaboration tool, we needed something as simple as generating patches
 13+but the ease-of-use of pull requests.
 14 
 15 The goal is not to create another code forge here. The goal is to create a very
 16 simple self-hosted git solution with the ability to collaborate with external
 17@@ -12,97 +22,95 @@ All an external contributor needs is:
 18 - An SSH keypair
 19 - An SSH client
 20 
 21-# patch requests
 22+# the problem
 23 
 24 Email is great as a decentralized system to send and receive changes (patchsets)
 25-to a git repo. However, setting up your email client and understanding the
 26-potential gotchas during that flow cannot be understated. Further, because we
 27-are leveraging the email protocol for communication and collaboration, we are
 28-limited by its feature-set. In particular, it is not possible to make edits to
 29-emails, so if there are typos or the contributor forgot to include some code or
 30-a line in the cover letter, there is a lot of back-and-forth noise to make those
 31-corrections.
 32-
 33-Further, when a contributor provides a patchset and receives feedback, the
 34-contributor must submit another patchset via email. These are completely
 35-separate and the only way to correlate them is via naming convention (e.g.
 36-[PATCH] xxx v2). Now when reviewing patchsets submitted to a project, the user
 37-must search for all versions of that particular patchset. These are separate
 38-conversations with potentially very different patches spanning across the time
 39-of a project. Maybe that's ok, but people are very used to a PR containing all
 40-changes and reviews across time, and I think it makes a lot of sense to have a
 41-single view of all conversations related to a change request.
 42-
 43-Another issue with the email workflow is knowing how to properly reply to a
 44-patchset. There is a lot of education on "doing patchsets right via email."
 45+to a git repo. However, onboarding a new user to a mailing list, properly
 46+setting up their email client, and then finally submitting the code contribution
 47+is enough to make many developers give up. Further, because we are leveraging
 48+the email protocol for collaboration, we are limited by its feature-set. For
 49+example, it is not possible to make edits to emails, everyone has a different
 50+client, those clients have different limitations around plain text email and
 51+downloading patches from it.
 52 
 53 Github pull requests are easy to use, easy to edit, and easy to manage. The
 54 downside is it forces the user to be inside their website to perform reviews.
 55 For quick changes, this is great, but when you start reading code within a web
 56 browser, there are quite a few downsides. At a certain point, it makes more
 57 sense to review code inside your local development environment, IDE, etc.
 58-Further, self-hosted solutions that mimick a pull request require a lot of
 59-infrastructure in order to manage it. For example, before an external user who
 60-wants to contribute to a repo, they first need to create an account and then
 61-login. This adds quite a bit of friction for a self-hosted solution, not only
 62-for an external contributor, but also for the code owner who has to provision
 63-the infra.
 64-
 65-Instead, I want to create a self-hosted git "server" that can handle sending and
 66-receiving patches without the cumbersome nature of setting up email or the
 67-limitations imposed by the email protocol. Further, I want the primary workflow
 68+
 69+Further, self-hosted solutions that mimic a pull request require a lot of
 70+infrastructure in order to manage it. A database, a web site connected to git,
 71+admin management, and services to manage it all. Another big point of friction:
 72+before an external user submits a code change, they first need to create an
 73+account and then login. This adds quite a bit of friction for a self-hosted
 74+solution, not only for an external contributor, but also for the code owner who
 75+has to provision the infra. Often times they also have to fork the repo within
 76+the code forge before submitting a PR. Then they never make a contribution ever
 77+again and keep a forked repo around forever. That seems silly.
 78+
 79+# introducing patch requests (PR)
 80+
 81+Instead, we want to create a self-hosted git "server" that can handle sending
 82+and receiving patches without the cumbersome nature of setting up email or the
 83+limitations imposed by the email protocol. Further, we want the primary workflow
 84 to surround the local development environment. Github is bringing the IDE to the
 85-browser in order to support their workflow, I want to bring the workflow to the
 86+browser in order to support their workflow, we want to bring the workflow to the
 87 local dev environment.
 88 
 89-I see this as a hybrid between the github workflow of a pull request and sending
 90-and receiving patches over email.
 91+We see this as a hybrid between the github workflow of a pull request and
 92+sending and receiving patches over email.
 93 
 94 The basic idea is to leverage an SSH app to handle most of the interaction
 95 between contributor and owner of a project. Everything can be done completely
 96 within the terminal, in a way that is ergonomic and fully featured.
 97 
 98+Notifications would happen with RSS and all state mutations would result in the
 99+generation of static web assets so it can all be hosted using a simple file web
100+server.
101+
102 ## format-patch workflow
103 
104 ```bash
105-# Owner hosts repo `noice.git` using pico/git
106+# Owner hosts repo `noice.git` using github
107 
108 # Contributor clones repo
109-git clone git.sh:/noice.git
110+git clone git@github.com:user/noice.git
111 
112 # Contributor wants to make a change
113 # Contributor makes changes via commits
114 git add -A && git commit -m "fix: some bugs"
115 
116 # Contributor runs:
117-git format-patch --stdout | ssh git.sh pr noice
118-# > Patch Request has been created (ID: noice/1)
119-
120-# Contributor can copy down patch request metadata:
121-rsync git.sh:/noice/1.md .
122-# Contributor edits patch request metadata, then runs:
123-rsync 1.md git.sh:/noice/
124+git format-patch --stdout | ssh pr.pico.sh pr create noice
125+# > Patch Request has been created (ID: 1)
126 
127 # Owner can checkout patch:
128-ssh git.sh pr noice/1 | git am -3
129-# Owner can comment in code, then commit, then send another format-patch
130-# on top of it:
131-git format-patch --stdout | ssh git.sh pr noice/1 --review
132-# We do some magic in the UI to make this look like comments or someway to
133-# clearly mark as a review
134-
135-# Owner can reject a pr:
136-ssh git.sh pr noice/1 --close
137-# (-maybe-) Owner can merge a pr:
138-ssh git.sh pr noice/1 --squash-n-merge
139+ssh pr.pico.sh pr print 1 | git am -3 -i
140+# Owner can comment (IN CODE), commit, then send another format-patch
141+# on top of the PR:
142+git format-patch HEAD~1 --stdout | ssh pr.pico.sh pr review 1
143+# UI clearly marks patch as a review
144 
145 # Contributor can checkout reviews
146-ssh git.sh pr noice/1 | git am -3
147+ssh pr.pico.sh pr print 1 | git am -3 -i
148 
149 # Commenting
150-cat my_comment.md | git.sh txt noice/1
151+cat my_comment.md | pr.pico.sh comment 1
152+
153+# Owner can reject a pr:
154+ssh pr.pico.sh pr close 1
155+
156+# Owner can accept a pr:
157+ssh pr.pico.sh pr accept 1
158 
159-# rinse and repeat
160+# Owner can cleanup PR:
161+ssh pr.pico.sh pr print 1 | git am -3 -i
162+
163+# Then push to upstream
164+git push origin main
165+
166+# Done!
167 ```
168 
169 The fundamental collaboration tool here is `format-patch`. Whether you a
170@@ -124,43 +132,6 @@ users. Just send reviews as code and write comments in the programming language
171 you are using. It's the job of the contributor to "address" those comments and
172 then remove them in subsequent patches.
173 
174-## branch workflow
175-
176-It's definitely possible for us to figure out a way to let the contributor
177-simply push a branch and create a patch request automatically, but there are
178-some rough edges to figure out there in order for it to work well.
179-
180-The flow would be virtually the same as `format-patch` except the contributor
181-would push a branch and we would automatically create a `format-patch` against
182-the base branch and then funnel it into the Patch Request. We don't want
183-external contributors to be able to push branches into the owner's git remote
184-because that has all sorts of opportunities for abuse. Instead we need to figure
185-out how to either fork the owner's repo and let the contributor push to that
186-fork seamlessly, or we just generate patchsets based on the contributor's branch
187-and the owner's base branch.
188-
189-This flow probably feels the most comfortable for Github users, but technically
190-more difficult to implement. Right out of the gate we need to know what base
191-branch the contributor wants to merge into. Then we need to figure out how to
192-perform reviews and followup code changes.
193-
194-This feels feasible, but technically more difficult. Further, I still want to
195-support patchsets via `format-patch` because it is a very elegant solution for
196-simpler changes.
197-
198-# web interface
199-
200-The other idea is to make the git web viewer completely static. Whenever an
201-owner pushes code, we generate all the static assets for that branch. We already
202-have a working prototype [pgit](https://github.com/picosh/pgit) that mostly
203-works. Further, any patch request that gets submitted would also be statically
204-generated. If we don't have a web portal with authentication and the ability to
205-manage a repo / patch request inside the web viewer, then a static site becomes
206-possible. This makes the web component of a git server much simpler, since it is
207-just static assets. All we need to do is install a git hook that properly
208-generates the static assets. For patch requests, everything comes through our
209-SSH app so we can generate the assets when those commands are being run.
210-
211 # research
212 
213 - https://git-scm.com/docs/git-format-patch