Clarification on Release class

cael commented

2025-05-26 09:56:03 +00:00

Hello,

I work at Inria and I'm part of the CodeCommons project (which extends Software Heritage). We're using the Friendly Forge Format model for our developments, and I have some questions about the Release class:

Does the Release class represent any commit?
If so, does the index field correspond to the commit number in GitLab or GitHub?
Can the tag_name field be empty if the commit does not have an associated tag?
The documentation says that "target_commitish is unused if the tag already exists."
Does this mean it is empty when tag_name is not empty?
What does the prerelease field represent exactly?
Is it true when this is a commit with no tag ? So is it equivalent to an empty tag_name?

Thanks in advance for your help, and thank you for your great work on F3!

Best regards

Hello, I work at Inria and I'm part of the [CodeCommons](https://codecommons.org) project (which extends [Software Heritage](https://www.softwareheritage.org)). We're using the Friendly Forge Format model for our developments, and I have some questions about the [Release](https://f3.forgefriends.org/schemas/index.html#release) class: * Does the Release class represent any commit? If so, does the index field correspond to the commit number in GitLab or GitHub? * Can the tag_name field be empty if the commit does not have an associated tag? * The documentation says that "target_commitish is unused if the tag already exists." Does this mean it is empty when tag_name is not empty? * What does the prerelease field represent exactly? Is it true when this is a commit with no tag ? So is it equivalent to an empty tag_name? Thanks in advance for your help, and thank you for your great work on F3! Best regards

limiting-factor commented

2025-05-26 12:32:26 +00:00

Owner

First of all, a word of warning: although it has the appearance of maturity, keep in mind that F3 is not currently used anywhere for real anywhere. I'm working on changing this but it won't happen overnight.

Today's breaking change changing assets into attachments so that it can be unified between releases and comments shows there still is room for improvement at a basic level.

This may be disappointing if you expected a more mature specification. But it also means there is more flexibility to changing it to fit your needs.

I'll answer your questions in a separate comment.

First of all, a word of warning: although it has the appearance of maturity, keep in mind that F3 is not currently used anywhere for real anywhere. I'm working on changing this but it won't happen overnight. Today's breaking change changing assets into attachments so that it can be unified between releases and comments shows there still is room for improvement at a basic level. This may be disappointing if you expected a more mature specification. But it also means there is more flexibility to changing it to fit your needs. I'll answer your questions in a separate comment.

limiting-factor referenced this issue from a commit

2025-05-26 12:57:00 +00:00

fix: clarify the documentation for the release

limiting-factor referenced this issue from a commit

2025-05-26 12:57:05 +00:00

fix: clarify the documentation for the release

limiting-factor referenced this issue from f3/f3-schemas

2025-05-26 12:57:31 +00:00

fix: clarify the documentation for the release #20

limiting-factor commented

2025-05-26 13:00:29 +00:00

Owner

f3/f3-schemas#20/files hopefully answers your questions.

Does the Release class represent any commit?
If so, does the index field correspond to the commit number in GitLab or GitHub?

It represents:

https://code.forgejo.org/f3/f3-schemas/pulls/20/files hopefully answers your questions. > Does the Release class represent any commit? > If so, does the index field correspond to the commit number in GitLab or GitHub? It represents: * https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release * https://docs.gitlab.com/api/releases/ * https://code.forgejo.org/api/swagger#/repository/repoCreateRelease

cael commented

2025-05-26 16:01:31 +00:00

Author

Thanks a lot for your answers.
We need a unified model to handle data from different forges, and we try to avoid introducing "yet another data model".
We've done some research and we like the F3 model. I'm just trying to understand it better in order to make the best use of it. :-)

I understand the definition of Release, so which object in F3 corresponds to a commit?

Thanks a lot for your answers. We need a unified model to handle data from different forges, and we try to avoid introducing "yet another data model". We've done some research and we like the F3 model. I'm just trying to understand it better in order to make the best use of it. :-) I understand the definition of Release, so which object in F3 corresponds to a commit?

earl-warren commented

2025-05-27 06:35:16 +00:00

In the spirit of keeping things minimal, F3 does not re-implement or re-define what is already found in a VCS (commits, tags, etc.). A F3 archive is composed of (i) JSON files organized hierarchically (ii) a VCS (iii) a collection of content addressable files (objects used for attachments, release assets etc.).

There is an ambiguity / problem regarding the notion of "commit" which is not identical across all VCS and I think it should be clarified, but this could be discussed in a different issue for clarity.

IMHO, for the purpose of unification assuming that a "commit" is a "Git commit" is the best choice for the years to come because:

Git has become the de-facto standard
There are converters from all other VCS to Git

Trying to create an abstract definition of "commit", "tag", etc. would not be very difficult. But implementing tooling to do something with such representations would be a gigantic waste of time as it would duplicate what VCS already do. For instance when a forge wants to sync a F3 archive that contains a Git repository with a single change, it can use "git fetch" on the remote and be done with it. I can't begin to imagine how much work it would be to do the same without using Git.

But again, it is best discussed in a separate issue.

In the spirit of keeping things minimal, F3 does not re-implement or re-define what is already found in a VCS (commits, tags, etc.). A F3 archive is composed of (i) JSON files organized hierarchically (ii) a VCS (iii) a collection of content addressable files (objects used for attachments, release assets etc.). There is an ambiguity / problem regarding the notion of "commit" which is not identical across all VCS and I think it should be clarified, but this could be discussed in a different issue for clarity. IMHO, for the purpose of unification assuming that a "commit" is a "Git commit" is the best choice for the years to come because: - Git has become the de-facto standard - There are converters from all other VCS to Git Trying to create an abstract definition of "commit", "tag", etc. would not be very difficult. But implementing tooling to do something with such representations would be a gigantic waste of time as it would duplicate what VCS already do. For instance when a forge wants to sync a F3 archive that contains a Git repository with a single change, it can use "git fetch" on the remote and be done with it. I can't begin to imagine how much work it would be to do the same without using Git. But again, it is best discussed in a separate issue.

cael commented

2025-05-27 09:23:26 +00:00

Author

Don't worry, our purpose is not to implement another VCS.
Thank you very much for your answers and we'll be following the evolution of F3 with interest.

Don't worry, our purpose is not to implement another VCS. Thank you very much for your answers and we'll be following the evolution of F3 with interest.

limiting-factor closed this issue

2025-05-27 10:58:34 +00:00

Rows
Columns

Clarification on Release class #45