Foreign references file format


The pending pull request on ForeignReferences in Gitea introduces pairs to match the local index of an issue with the index of its counterpart during migration. There already exists something similar for users (ExternalUsers) in Gitea. This allows for incremental migration and mirroring: when migrating or mirroring an issue it is possible to figure out if the issue that exists in Gitea was previously migrated or mirrored from elsewhere and updated it to reflect the new state.

The same kind of association is necessary for federation. The local representation of an issue needs to be compared with the representation of the same issue in the federated forge. And for this purpose the local forge needs some kind of table to associate the local index of the issue with the remote index.

These associations carry an information that should be persisted in the friendly forge format. The state of a software project within a forge not only consists of issues, milestones, pull requests etc. It is also how each of these is linked with another forge. Here is how it could look like:

// Type* are valid values for the Type field of ForeignReference
const (
	TypeProject       = "project"
	TypeIssue         = "issue"
	TypePullRequest   = "pull_request"
	TypeComment       = "comment"
	TypeReview        = "review"
	TypeReviewComment = "review_comment"
	TypeRelease       = "release"

// ForeignReference foreign reference
type ForeignReference struct {
	LocalIndex   int64
	LocalURL     string
	ForeignIndex int64
	ForeignURL   string
	Type         string

There is nothing new in the idea that links between forges must be stored. But until the Gitea pull request it was unclear how such a link could be implemented natively in a forge. The proposed structure has pros and cons and will likely evolve over time. Very much like the current format for issues and pull requests, because they are tightly dependent on the current Gitea implementation. Their merit is to be a starting point that is likely to be accepted by Gitea and lead to a native federation implementation.


1 Like

The pull request introducing ForeignReferences was merged this week :tada: It is a something to build on. But it may be too early to introduce it as a new file format.

Iā€™m inclined to keep it an implementation detail for the software implementing the Friendly Forge Format. In the case of Gitea it means providing a factory that returns an object with an interface able to store and retrieve a foreign reference. And the Go reference implementation of the Friendly Forge Format provides a SQLite based alternative for test purposes.

1 Like