Advice on joint FRET development

[kquick]

I'm working on developing FRET models in conjunction with other developers. FRET seems to save things in various places in my home directory (~/Documents/fret*, ~/.config/FRET), but I'm wanting to use a proper workflow, involving git version control.

I can manually export Requirements and Variables to JSON and use git to maintain those, but it does require manual steps on both ends, and I'm wondering if a JSON import will completely overwrite any changes to a project I've made locally or if it will merge them? What about conflicting changes?

Please let me know the best recommended practice for multi-developer, version-control-backed development with FRET.

[anmavrid]

Hi @kquick,

As you may know, FRET does not currently support version control. When you export requirements (e.g., as a JSON file), modify them, and re-import them into FRET, the tool does not merge or overwrite conflicts. Instead, each imported requirement is treated as a new entry, and FRET assigns a new unique _id (as seen in the exported JSON file). This means that even unchanged requirements will be re-added as new entries rather than updated.

FRET uses PouchDB as its database, and we had two implementation choices:

1. Use PouchDB’s update functionality to completely overwrite existing requirements during import.
2. Treat imported requirements as new entries by generating new _ids.

We opted for the second, less intrusive, approach to avoid overwriting local changes.

In the SpaceROS project, where multiple people collaborated on requirements across different tools, we addressed this by:

1. Maintaining a Git repository as the ground truth for FRET project requirements. Git helped us track history, manage conflicts, and merge changes from different users.
2. After resolving conflicts in Git, we either renamed or deleted the previous FRET project and then imported the updated version.

Would this approach work for you?

In SpaceROS, we also found that Markdown (MD) format was more readable for tracking changes with Git than our JSON export. Notice that the MD export only contains the following: Project name, Requirement name, Parent requirement FRETish text, and Rationale. Eg, it does not contain the generated formalizations.

While the public version of FRET currently includes MD export, it does not have the MD import. If MD import would be useful to you, we could add it in the public version for the next release.

Thanks,
Anastasia

[kquick]

Hi Anastasia,

Thanks for the info, that's very helpful.

I am not sure if the Markdown would be more helpful or not. I have the following observations/concerns:

• The JSON contains a considerable amount of information, including generated formulae, so it appears to be the output of the requirements analysis process. The Markdown format is a simple markdown table with just the English syntax and thus appears to be the input to the requirements analysis. This latter is more useful if there would be any modifications to the requirements outside of FRET (via direct user editing or tooling), but...
• The JSON format can be emitted with associated variable information, whereas the Markdown format does not support variable information (at least for exporting). Because the requirements analysis process requires definitions of the variable formats, it seems like the "Requirements and Variables" JSON format is the only option available to us.

In the unreleased Markdown import, is it possible to also provide variable definitions, and does that version support variable definitions in Markdown export as well? If that were the case, I think we might prefer Markdown format, otherwise I think we are restricted to the JSON format (although I have concerns about internal consistency in that case should the JSON ever be changed outside of FRET).

-Kevin

[anmavrid]

Hi Kevin,

That's a great point.

When we worked on the SpaceROS project, our initial focus was solely on exporting requirements, not variable information. In fact, we introduced the option to export variables at a later point.

Currently, we only support variable import/export in JSON format. Right now, our main focus is on releasing FRET v3, but we can explore adding support for variable import/export in MD format in a future release.

Thanks,
Anastasia