Reply sent to NLnet today
Hi,
URL of the WorkPlan: Project Plan: Friendly Forge Format (F3) - HedgeDoc
Thanks a lot for taking a close look, it is helpful and the questions are relevant. I’ll try to answer them as much as I can but do not hesitate to let me know if I fail to clarify.
- Could you help us understand the plan better by adding a sentence or two to the tasks? The section “Specifications Tooling” has a nice explanation, but e.g. “Idempotency” leaves me guessing what the task’s context, scope and and purpose is.
My bad, it is indeed subject to multiple interpretations. I added the following:
The API or the internals of a forge are not usually designed to be idempotent. For instance deleting an issue that does not exist, either because it never did or because it was just deleted, will not succeed. However an implementation of F3 must be idempotent: uploading the same F3 archive twice must not lead to the creation of two different set of objects. For that to be possible the F3 format must ensure it contains all the information required for an implementation to be idempotent despite the lack of idempotency of the API or of the internals of the target forge.
- In the first task: “as published in WikiData” → is wikidata reliable and up-to-date on software forge features? Or do you also expect to contribute data to wikidata here?
I added this, good point. I have spent month working on WikiData in the past and I know what it entails.
- Update WikiData as needed if information is found missing
I was pleasantly surprised by the forge inventory that exist in WikiData and I’m not expecting it will need too much work. It is not perfect of course but the very important thing is that it is the one place where such an inventory can be maintained collaboratively.
- With downloading/uploading from/to “the API”, which API are we talking about? The API of a particular forge software?
Yes. To clarify I added the following definition:
An API is a REST API published by a given forge. For instance Forgejo API for Forgejo or REST API | GitLab for GitLab.
- In the proposal you write about the relation to ForgeFed, e.g.: “Improvements to the ForgeFed specifications will be proposed so that data contained in a F3 archive can be translated and sent over ActivityPub.” We don’t see this reflected in the plan, while it seems worthwhile to try find maximum convergence between the projects. Might it be worth trying to create shared schemas, (RDF) vocabulary, or clearly defined mappings? When I see both ForgeFed Modeling and Friendly Forge Format (F3) / F3 schemas · GitLab I wonder if we are not inventing two wheels here.
When the proposal was written the situation was quite different. Neither Anthony Wang nor fr33domlover were funded to work on ForgeFed. Today they both are and we’ve had discussions about how F3 fits with ForgeFed. In a nutshell it is a layer ForgeFed can rely on for its implementation and we are coordinating to unify the terms.
Here is a list of what F3 and ForgeFed share as of today.
Mapping
Only the fields that have a correspondence are represented here
- ForgeFed Modeling => Comment — F3 Publisher documentation
- ref / name => ref
- ForgeFed Modeling => Comment — F3 Publisher documentation
- hash => sha
- ForgeFed Modeling => Comment — F3 Publisher documentation
- name => name
- summary => description
- ForgeFed Modeling => Comment — F3 Publisher documentation
- actor => poster_id
- target => base
- hashAfter => head
Not yet represented in F3
Not in scope for F3
- ForgeFed Modeling => Hierarchy — F3 Publisher documentation the repository itself is included in F3 as a binary blob would, opaque and not to be defined by F3 other than knowing it is of a given type (git, mercurial etc.)
- ForgeFed Modeling because it belongs to git
- ForgeFed Modeling because models used to implement access control behavior does not belong in an archive format
It is great that we have the mean and the will to work together and I fully expect this will continue to be the case during the duration of this grant. However, I cannot commit to a deliverable that would be specific enough to be included in the workplan, primarily because I can’t be sure where ForgeFed is going to be in six months from now.
- With the V1/“first release”, do you mean the release of both the spec&tooling?
Yes. The general idea is that a release contains everything a third party would need to improve the specification on their own and verify it works as intended. I added the following:
A F3 release consists of the specifications, the compliance tests and the release tooling.
- What form will the tooling take? A command line tool that I can give a gitlab and gitea URL, and it will migrate my project? Or/and an integration (e.g. plugin/webhooks-based) in those forges in some form, to mirror a project to another forge? Or/and some web interface? Or…?
The tooling is a set of CI pipelines. They will rely on scripts that could also be run independently but that is an internal detail. Someone willing to use the tools (compliance and release) will simply add them in a forge instance, trigger the CI to run them and wait for the result to show in the forge interface.
- The compliance tests for Forgejo, Gitea, and GitLab; does that mean a test suite that creates actual instances of those forges with test data, exports and imports the data between them, and checks the results?
Exactly. I added the following to clarify.
Compliance testing is a fully automated CI pipeline that create a new forge instance for the duration of the test. Each test demonstrates a particular aspect of the F3 specification can actually be implemented for this particular version of the forge. For instance a test will spawn a Forgejo v1.18 instance, upload a new issue via the API from a compliant F3 issue, download it back using the API and verify the result is a well formed comparable F3 issue.
- Is GitHub out of scope in this project?
It is not: it will be included in the inventory/comparison. But being proprietary it would be too difficult to include it in the implementation of the tooling and tests in the context of this grant. However, since both Forgejo and Gitea implement a REST API similar to GitHub, it will partly be covered.
Sincerely
(but also feel free to come back with further questions/suggestions)