About the Friendly Forge Format (F3)

The Friendly Forge Format (abbreviated F3) is an Open File Format for storing the information from a forge such as issues, pull/merge requests, milestones, release assets, etc. as well as the associated VCS (Git, Mercurial, etc.).

Description

F3 is designed to exchange the state of a software project between GitHub, GitLab, Gitea, etc. for backup, mirroring or federation.

F3 is essential for a forge to provide key requirements:

  • Portability: the entire state of a software project can be dumped and restored at a later time, on a different development environment.
  • Versatility: when published and updated as a F3 archive, a software project effectively is Open Data on which an unlimited range of applications can rely, even outside of the forge domain
  • Consistency: it provides a common language to use when talking about the forge related domains
  • Trust: cryptographic signatures on each F3 dump guard against malicious or unintentional tampering that could compromise the integrity of a software project

And it unlocks the following use cases:

  • Analytics: data mining the contents of files is more practical than issuing a large number of queries to an API
  • Mirror: issues and all other aspects of a software project can be conveniently mirrored from a forge to another by publishing a F3 archive in a VCS and acting on the changes
  • Archival: storing F3 archives in a VCS makes it easier for them to be preserved in long term archives such as Software Heritage
  • Reporting: forgefed messages can be created from F3 and sent via the ActivityPub protocol

F3 is developed with a bottom up approach: it starts from the internal format used by Gitea and builds upon it. However imperfect, by being compatible with an existing implementation from the start it creates a feedback loop that allows F3 to evolve into a standardized format with broad adoption by forges and related development tools. Reference implementations in Go, Python and Ruby supporting a range of development environments are released together with the specifications.

New versions of F3 are published as it improves to support the ever growing variety of forges. Each release comes with guarantees that make it convenient to integrate and maintain in various workflows:

  • Complete, precise and unambiguous documentation
  • Versioned releases with actionable release notes
  • Cryptographically signed archives
  • Backward compatible
  • Upgradable

F3 is modular and extensible so that contributors can work on a particular feature with a quick learning curve that allows for crowdsourcing. A robust test infrastructure running a variety of forges verifies every changes and ensures the technical debt is kept to a minimum. To avoid effort duplication, the Go reference implementation is wrapped in other languages such as Python or Ruby.

Repositories

All repositories are in the Friendly Forge Format group.

  • F3 Schemas are the JSON Schemas for issues, milestones, etc.
  • F3 Go is the Go reference implementation of F3. It provides JSON validation, converting from a remote forge to F3 and from F3 to a remote forge. The F3 Schemas repository is a submodule of F3 Go.
  • F3 Python is the Python reference implementation of F3. It is a Python wrapper around the F3 Go package.
  • F3 Publisher contains the F3 specifications and is associated with a CD pipeline that publishes the HTML formatted F3 specifications into the F3 HTML repository and at https://f3.forgefriends.org via librepages. The F3 Schemas repository is a submodule of F3 Publisher.
  • F3 HTML is a HTML version of the F3 specifications created by the CD of the F3 Publisher repository.
2 Likes