In the following the objectives and activities are roughly listed in chronological order (the Go implementation must happen before the release) but some of them can be conducted in parallel (the User Research can happen at the same time as the Go implementation up to the point where the API must be implemented). #### Objectives ##### User Research In the spirit of [focusing on what the user needs and not the product](https://jdittrich.github.io/userNeedResearchBook/#our-inquiry-concerns-the-user-not-our-future-product), we [prepare our research](https://jdittrich.github.io/userNeedResearchBook/#prepare-your-research) starting with [finding participants ](https://jdittrich.github.io/userNeedResearchBook/#find-participants) among software developers, organizations and forge maintainers. The findings of the User Research are summarized in [a report](https://jdittrich.github.io/userNeedResearchBook/#reports) concluded by recommendations that should be followed by the F3 specification implementors. ##### Community engagement The long term sustainability of the F3 specifications and reference implementation require a strong engagement from a diverse community of volunteers coordinated by paid staff. It requires a technical infrastructure that allows for quick onboarding, a curated lists of easy tasks and more generally all the best practices recommended for Free Software projects. Although it can be expected to happen over time, an effort will be made to reach this objective sooner rather than later. It is transversal to all activities, from the evolution of the documentation to the release process itself up to the governance of the project. The best volunteers should be empowered with a clear path to participation, from the smallest task achievable within a few hours up to a daily involvement to transform the governance of the F3 project itself. This objective is not achieved by specific activities, it is done by accomplishing each activity with this particular state of mind. ##### Specification and documentation This is the core of the project and will be released as a reference document explaining the F3 format. A bottom up approach is preferred because it is usable within a reasonable time frame. F3 starts with the internal format used by the Forgejo project because it has a better chance of being implemented natively and reach a significant audience. From there, the format is generalized, the documentation improved until it can be applied in the context of other forges. The "bottom" is the Forgejo internal format and it is incrementally improved "up" to the point where it fits all existing forges. By contrast, a top down approach that would consist of designing a theoretical format would be very challenging as it requires a consensus from all forge implementors to be approved. ##### Go package reference implementation The Go reference implementation for F3 is meant to cover all aspects of the specifications. It is developed at the same time as the specifications, in a short feedback loop that allows to quickly identify aspects of the specification that are either ambiguous, difficult to implement or understand. It provides three interfaces: * The command line interface which is most convenient for exporting and importing a software project from and to a software forge that does not yet natively implement the F3 format. * The F3 API which is meant to be used for high level import, export and mirror operations. * The F3 driver API which is meant to be used by forge implementors to natively support F3. The simpler native integration using the F3 API would rely on the REST API of the forge and require little work from the implementor. But it would also be subject to the limitations imposed by the API (such as assigning identifiers to objects like issues or milestones). The better native integration requires writing a F3 driver to use the internals of the forge and use functions not available from the API. ##### Python package reference implementation The Python reference implementation demonstrates how the Go package can be used from another language. It could be used by the Pagure forge to provide basic import, export and mirroring features. Such an integration would not require the implementor to know the details of the F3 specifications as the bulk of the work is already implemented in the Go package. Only the F3 API is available in this context. The value of this implementation is primarily to encourage developers to share a single implementation of the format rather than fragmenting its interpretation by working on multiple implementations in many languages. ##### First release The release of the F3 format is published simultaneously with the Go reference implementation, under the same semantic version. It provides the following guarantees to the user: * Backward compatibility: * Every effort is made for a version to be compatible with the previous versions * If a breaking change cannot be avoided, the reference implementation provides a conversion method to upgrade existing F3 archives * Non ambiguous: each aspect of the specifications is precisely documented, the reader does not need to interpret ambiguous statements * Semantic versioning: the user knows if a breaking change is introduced by reading the version number * Detailed release notes: each modification to the specification is explained in detail in the release notes so the reader can to understand their consequences without exploring other sources of information The development releases happen once a month but do not provide the same guarantees. The stable releases of the reference implementation may receive security patches and bug fixes but will not receive new features. Similarly, the stable releases of the specifications may receive patches when an error is found or an ambiguity requires rewording but their semantic will not change. ##### Integration in the Forgejo codebase The Go reference implementation is the basis of a native integration in the Forgejo codebase which is also written in Go. There is strong support in the Forgejo developer community to provide a native integration with F3. The user base is not large (above 50,000 users and a few hundred instances) but it is an ideal environment to field test early versions of F3. Since Forgejo includes all of the Gitea codebase, there will be no technical difficulty for F3 to be integrated in Gitea. Since F3 is an emerging standard, the incentive for a native integration is low. But the existence of a working implementation in Forgejo lowers the barrier for adoption. The native integration of F3 in Forgejo is also a concrete showcase for GitLab developers to get inspiration from and for GitLab users to realize what data portability would mean for their own software projects. ##### Submission to a standard body Although it is premature to expect that F3 is accepted by an standard body, the process to develop a new standard within OASIS or W3C is very involved and it should be engaged as soon as possible. The objective is to properly apply to at least one standard body and share the required knowledge with all members of the community working on the F3 specifications and reference implementation. #### Activities ##### User Research * [Prepare the research ](https://jdittrich.github.io/userNeedResearchBook/#prepare-your-research) * [Find participants ](https://jdittrich.github.io/userNeedResearchBook/#find-participants) among software developers, organizations and forge maintainers * [Prepare the research sessions](https://jdittrich.github.io/userNeedResearchBook/#prepare-the-research-session) * Create an intercept interview script * Conduct interviews with the participants * Organize an [affinity mapping session ](https://www.nngroup.com/articles/affinity-diagram/) to identify [emerging themes](https://www.researchgate.net/profile/Virginia_Braun/publication/235356393_Using_Thematic_Analysis_in_Psychology/links/00b7d52c9e6303d840000000/Using-Thematic-Analysis-in-Psychology.pdf) * [Analyze the results](https://jdittrich.github.io/userNeedResearchBook/#Analysis) and [write a report](https://jdittrich.github.io/userNeedResearchBook/#communicate-results) with recommendations Deliverable: A User Research report including recommendations for developing F3 Effort: 10 days ##### Specification and documentation The F3 Specification includes: * An introduction * JSON Schema with embedded documentation * Release notes * A normative file hierarchy * A glossary of terms and their definition Deliverables: * JSON Schema for F3 are published in a dedicated repository * The documentation is published on a public web site Effort: 30 days ###### Go package reference implementation A reference implementation of F3 in Go provides: * An API for integration in a forge written in Go * Validation of a F3 archive (JSON Schema validation, VCS sanity checks) * Import, Export and Mirror support for Forgejo, Gitea and GitLab * Dataset generators and fixtures to verify the conformance with the specifications Deliverable: The Go package is published at https://pkg.go.dev/ Effort: 70 days ##### Python package reference implementation A reference implementation of F3 in Python provides: * An API for integration in a forge written in Python * The same features as the Go package reference implementation Deliverable: The Python package is published https://pypi.org/ Effort: 5 days ##### First release The first F3 release is a bundle that includes: * The specifications and documentation * The Go reference implementation * The Python reference implementation They are verified to be consistent and tagged with the same version number. Deliverable: simultaneous publication of F3 version 1.0.0 at: * https://readthedocs.org/ for the specifications * https://pypi.org/ for the Python reference implementation * https://pkg.go.dev/ for the Go reference implementation Effort: 5 days ##### Integration in the Forgejo codebase The F3 Go reference implementation is proposed as an alternative to the internal format used for repositories dump and restore features in the Forgejo codebase. Deliverables: pull request merged in https://forgejo.org Effort: 5 days ##### Submission to a standard body Reach out to OASIS and propose F3 as a new standard. Deliverable: A submitted application acknowledged as received by OASIS Effort: 5 days