---
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.