Forge

Work in progress.

Lindenii Forge aims to be an uncomplicated yet featured software forge, primarily designed for self-hosting by small organizations and individuals.

The Lindenii project itself runs an instance, where the official source repository of Lindenii Forge is located.

Organization

Misc URLs (for hosting stylesheets, scripts, the login page, etc.) are like https://forge.example.org/-/functionality....

Contentful URLs are like https://forge.example.org/group_name/subgroup_name.../-/module_type/module_name.

The available module_types are:

repos for version control (the only one implemented so far)
tickets for ticket trackers
discuss for discussions
decisions for requests for comments and collective decision-making

Group and subgroup names may not be -.

While this syntax looks a bit odd, it makes it possible to unambiguously identify where subgroups end and modules begin, without needing to touch the database.

Protocols and user interfaces

The following should be roughly equivalent in functionality:

Web interface
Custom TLS-based API
HTTP GraphQL API

The following shall function where they make sense:

User-friendly SSH interface
Email interface

Features

Git repos

Viewing commits and patches
Viewing trees and files
Viewing arbitrary hashed objects and refs
Viewing tags

Merge requests

Each version-controlled repo (“main repo”) has an area for merge requests (“MR”s) which may be optionally enabled. A MR is a request to merge changes from one branch (“source branch”) into another (“destination branch”), in the same repo. The source branch usually, but not always, begins with contrib/.

Unsolicited pushes to contrib/... automatically open a MR, returning instructions to edit the description and manage the MR further, via the SSH standard error channel.
Patches received from email will be automatically converted into MRs.
The web interface and APIs (to create MRs from existing branches).

MR branches will be synced to automatically created MR-specific mailing lists. These mailing lists should have archives accessible via read-only IMAP. The contents of merge requests are presented as what would be produced from git-send-email.

It should also be possible for people to perform code reviews via email by interwoven a quoted patch with replies, and all these replies should be synced to the main MR database, presented via IMAP and the Web interface.

This is probably the most unique feature of Lindenii Forge: while the general structure is similar to Forgejo-style pull requests, MRs are automatically created based on branch namespaces (similar to Gerrit in some respects) and are synced to mailing lists. This allows users to submit MRs via email, or git push, or the Web interface, or the API, to support developers with different workflows.

Ticket tracking

Ticket tracking works like todo.sr.ht, though we also intend to support IMAP for viewing them and downloading them locally for later use.

Directed acrylic graphs or other dependency mechanisms may be considered in the far future.

It should be possible to associate tickets with MRs.

Requests for comments and decisions

Requests for comments (RFCs) and decisions are similar to tickets, but specifically designed for collective decision-making.

In general, there will be two or more sides to a question, and people may use commentaries to express their opinions. Group voting is supported for RFC trackers that choose so; others may use dictatorial voting. At the end of decisions, there shall be a final rationale, and users may submit concurring or dissenting opinions.

It should be possible to associate RFCs with MRs too.

Discussions

Discussions are basically mailing lists that could also be used from a Web interface. IMAP archive should be provided.

Discussions are not designed to handle patchsets. Patchsets should be send to the corresponding repo, where they are turned into Lindenii patchsets.

Mailing list messages are expected to be plain text. A subset of markdown shall be considered. No full-HTML emails are expected for normal traffic.

CI

We generally prefer to have linters, deployment pipelines and such run on each local developer’s machine, for example as a pre-commit hook. However there are reasons why CI might be useful.

We plan to integrate a builds.sr.ht-style CI in the future.

Authentication and authorization

Anonymous SSH and HTTPS read access is possible for public repos.
Git write access is authenticated via SSH public keys.
The TLS API will be authenticated with TLS client certificates.
The web interface has a dedicated login screen. Logins are remembered with cookies. A dropdown box will be available to select the time the user wishes to remain logged in.
Commit validation based on SSH signature validation will be implemented.

Federated authentication

We probably won’t fully support ForgeFed because it’s way too bloated. However, some type of federated authentication may be considered.

Since Forgejo, SourceHut, and GitHub all publicly serve their users’ SSH keys, people who submit merge requests by pushing via SSH into the branch namespace may link their SSH keys to an identity on an external forge. We will also serve users’ SSH keys, but it would be opt-in.

OpenID Connect will likely not be supported.

This plan is subject to change.

License

We are currently using the GNU Affero General Public License version 3.

The forge software serves its own source at /-/source/.

Support and development

We hang out in #chat and #lindenii on irc.runxiyu.org. The latter is bridged to #lindenii on Libera.Chat.
We currently use todo.sr.ht since our own ticket tracking system is not ready yet. Please submit patches by pushing to contrib/... in the official repo.
We have several Git repo mirrors on a few places: