commit 028ccb39fc93171b6237e6a17f743ac614b3a6cb
from: Stefan Sperling <stsp@stsp.name>
date: Mon Jun 24 10:10:57 2024 UTC

add some initial notes about design

commit - /dev/null
commit + 028ccb39fc93171b6237e6a17f743ac614b3a6cb
blob - /dev/null
blob + 55b3a956c4b69b9717ffa525b0e909e27dd57b68 (mode 644)
--- /dev/null
+++ notes
@@ -0,0 +1,84 @@
+= Bug Tracking =
+
+A web interface where users and developers can store information
+about bugs. Underlying storage should be in Git, such that anyone
+can clone the repository, run a tool of ours (such as gotwebd?)
+and read and modify issues. Ideally, a simple 'got send' of special
+refs would be enough to update issue data in the main repository.
+Hence the storage format we used must be merge-conflict-free by design.
+
+Blueprint for workflow of a good bug tracker using "user pain":
+https://lostgarden.com/2008/05/20/improving-bug-triage-with-user-pain/
+
+There is an unfortunate practice of overlaying bug tracking with feature
+requests and milestones. Bugs and feature planning are often mixed, e.g.
+in platforms like Trac and Redmine.
+Ideally, bugs and feature milestones should be kept separate in a very
+clear way, especially if we use the "user pain" approach.
+We could have a project planning UI that manages TODO items and milestones,
+separate from the bug tracker.
+
+
+= Pull Requests and Code Review =
+
+Some prior art:
+
+Storing review comments:
+
+https://github.com/google/git-appraise
+https://github.com/google/git-pull-request-mirror
+
+Storing PRs:
+
+Github uses a trick where forks and pull requests don't actually use
+separate repositories. Instead, they carve up the reference namespace
+such that each fork has its own set of refs. But the underlying storage
+is shared (greatly saving on disk space). We know this by word of mouth
+and because of bugs like this one, where a tree from the youtube-dl
+repository appears in the repository of DMCA takedowns:
+https://github.com/github/dmca/tree/416da574ec0df3388f652e44f7fe71b1e3a4701f
+
+We don't want such things to happen on gothub, so pull requests should use
+dedicated repositories which contain just the branch that is being proposed,
+including full history prior to this branch. This means PR storage will be
+costly, but PR repositories can be designed to be temporary.
+
+Workflow:
+
+1) alice clones bob.gothub.org/src.git to alice.gothub.org/src.git;
+alice.gothub.org and bob.gothub.org are project spaces which can have
+several committers each; however, we can expect some users will be using a
+project space just for themselves, and in the PR context this can make sense
+
+2) alice creates a branch in alice.gothub.org/src.git and does some work.
+When ready to send a PR, alice creates a dedicated repository at
+alice.gothub.org/foo.git and either provide anonymous read access or adds
+read credentials such that bob can access foo.git (recall that gotd doesn't
+support per-reference access rules, only per-repository rules);
+alice can also add notification details for bob to be notified of changes
+to foo.git via email, arbitrary notifications triggered by http/json (the
+gothub site could provide portals to notification providers, e.g. pushover)
+
+3) bob can clone from alice.gothub.org/foo.git to obtain a copy of the changes:
+bob receives notifications when alice sends changes to foo.git
+
+4) in bob.gothub.org/foo.git, bob can use a web UI to leave review comments
+on diffs and/or the full files, on line-by-line granularity;
+all data pertaining to code review is stored bob's repo within a dedicated
+refernce namespace;
+bob can add notification details for alice to be informed of code review
+commments
+
+5) alices can now react to review comments in two ways: leave comments at the
+code review UI for bob.gothub.org/foo.git (needs some way of authentication);
+make changes to code and/or branch history in alice.gothub.org/foo.git which
+bob can then fetch again to repeat the cycle
+
+6) once bob is happy, bob.gothub.org/foo.git can be added as a temporary
+remote of a clone from bob.gothub.org/src.git; bob fetches from foo.git,
+rebases/integrates/merges the branch, and sends to bob.gothub.org/src.git;
+optionally, code review comment history can be fetched from foo.git and
+retained in src.git ; this step can be done manually by bob following
+instructions, or it can be automated server-side
+
+7) alice.gothub.org/foo.git and bob.gothub.org/foo.git can be deleted