F3 Monthly update - April 2024


The F3 reference implementation needs a clear specification to resolve internal references (for instance a pull request referencing a branch repository). The F3 infrastructure was made more durable.


References resolution

The F3 specifications previously relied on references that were context dependent. For instance the poster of an issue was identified by the unique identifier of the user. But the nature of the reference (a user in this case) had to be specified for each field because it could not be deduced from the content of the field. All references were gradually changed to be paths (either absolute or relative) to the resource instead. A F3 implementation can use such a reference regardless of the resource (for instance a reference resolution for a code review is managed in the same way as for a pull request).

The specifications were updated with a section on references. An iterative algorithm for reference resolution can be used when mirroring resources. Mirroring a single project will have:

  • external references (for instance a user authoring an issue)
  • internal references (for instance a pull request that references a branch of the repository)

Their resolution has different requirements:

  • external references must be resolved by a shallow mirror before mirroring the resource (for instance a user is mirrored but the resources it owns are not, it is shallow in this way)
  • internal references may not exist and their resolution postponed (for instance a pull request may be mirrored before the repository it references)

Although F3 may contain cross references, they only happen within user generated textual content and not in the structure of the archive:

  • an issue comment A can have a reference to an issue comment B that also have a reference to the comment A, creating a loop
  • the F3 structure is a graph that has no loop (simple directed graph)

For the purpose of mirroring it is therefore possible to resolve internal references in an iterative way:

  • when creating resources, references to unknown resources are skipped
  • the mirroring repeats until all references are resolved
  • resolving references within textual content happens only after the structure is mirrored


With the agreement of the Forgejo community, a mirror of the F3 repositories was setup in their infrastructure.

Plans for the next month

  • Use the F3 CLI, as a standalone tool or embedded in Forgejo, to continue the debug loop that integrates user feedback
  • Auditing the features published by the two dominant software forges