forge: Add plans

1 files changed, 98 insertions, 0 deletions

diff --git a/content/forge/_index.md b/content/forge/_index.md
new file mode 100644
index 0000000..c0e4001
--- /dev/null
+++ b/content/forge/_index.md
@@ -0,0 +1,98 @@
+---
+title: Lindenii Forge
+---
+
+## Organization
+
+URLs are like `https://forge.example.org/project_name/module_type/module_name/...`.
+
+The available `module_type`s are:
+* `repos` for version control
+* `tickets` for ticket trackers
+* `mail` for mailing lists
+
+## Version-controled repos
+
+Currently we only support Git.
+
+### Pull requests
+
+URLs are like `https://forge.lindenii.runxiyu.org/forge/repos/daemon/pulls/7`.
+
+Each version-controlled repo ("main repo") has an area for pull requests
+("PRs") which may be optionally enabled. A PR is a request to merge (including
+alternate merge strategies such as rebase/squash, we do not necessarily use
+merge commits) a Git ref ("source ref") into a branch in the main repo
+("destination branch").
+
+When creating a PR from the API or Web interface, there is an option to create
+a subsidiary repo accessible via the PR's URL, which will become the source
+ref.
+
+When creating a PR from an emailed patchset, or when pushing with the `pr` push
+option, the subsidiary repo is created automatically:
+* When created from email, we look for the parent commit in the patchset,
+  populate the subsidiary repo with that commit, and apply the patch. (It's
+  slightly more complicated when a patchset contains multiple patches but it
+  goes similarly.) If this fails, the email is bounced safely, or is marked as
+  "orphaned" and would require manual intervention, depending on the repo's
+  settings.
+* When created from `git push -o pr`, the subsidiary repo is populated
+  automatically with whatever is being received by the push.
+
+Repos may have per-repo policies to only allow merging patchsets with a linear
+history, or to protect some branches, or may have other policies. These should
+be enforced by the in-house Git service.
+
+PRs have metadata such as reviewers, tags, statuses (incl. Draft), etc.
+
+PRs may be merged by multiple means:
+* The maintainer may fetch the source ref (which could be the subsidiary repo)
+  and merge it, and use a push option or git trailer to tell the system that
+  the PR has been merged.
+* The maintainer may use the Web interface and press the merge button.
+* The maintainer may use the API.
+
+It shall be possible to subscribe to an individual PR, or all PRs on a repo,
+via email, ressembling a mailing list interface. This is very natural for
+emailed patchsets, but will take some work for subsidiary repos that are pushed
+to, and for external refs. Perhaps we could just run `git format-patch` on the
+server before emailing it. The email headers shall contain relevant metadata.
+
+I'm not sure whether subsidiary repos should be deleted after merging/closing.
+Records must be kept anyway, and I think a subsidiary repo is more accurate
+than keeping a diff. But then we might run into disk space constraints; will
+have to look at some Git plumbing or even filesystem deduplication for that.
+
+## Mailing lists
+
+Mailing lists are not designed to handle patchsets. Patchsets should be send to
+the corresponding repo, where they are automatically turned into PRs.
+
+Mailing list messages are expected to be plain text. A subset of markdown shall
+be considered. No full-HTML emails.
+
+## Ticket trackers
+
+Basically works like todo.sr.ht.
+
+May be associated with PRs.
+
+Not sure how to implement dependencies yet, will think later. Perhaps a
+directed acyclic graph?
+
+## CI
+
+Not sure how to integrate this. I'm not going to touch this right now. Leaving
+until later.
+
+## Authentication, authorization
+
+Anonymous SSH read access should be possible for public repos. All other Git
+access should be done via SSH public keys. Custom SSH server implementation
+necessary due to OpenSSH limitations.
+
+I'm not sure how authentication should work in the API. I do not want to use
+OAuth 2.0.
+
+PGP patch validation is planned.