Summary
The user research was concluded and the report published. An analysis of the features recently published by GitLab and GitHub was conducted.
Tasks
User Research
The user research was concluded and the report published. The interviews revealed developers would greatly benefit from high quality data repository that provides them with:
- A stable data schema, backward compatible so the software they write does not unexpectedly break, with detailed release notes when it changes
- An exhaustive and up to date reference documentation for all data structure
- Downloadable data files with their modification history (i.e. git or another VCS) to know when new data is available and to see the differences when an update happens, for debugging purposes and tracking
Some findings were unexpected and heavily influenced the recommendations:
- All developers write scripts to cleanup the data and cope with errors originating from the software forges from which they download the data. This is a very significant part of their initial development and continues with the maintenance process when data needs to be updated. A reliable data repository that contains data that is carefully checked for errors before publication is a significant added value for all developers because it reduces their workload.
- Most forges make an effort to publish data in multiple formats and protocols but it turns out most developers transform the data they download instead of using the original version. Therefore using a single format that is universally supported (e.g. JSON) is enough.
- Most developers do not rely on the documentation: they try to guess the structure of the data and its meaning by observing the content of the forges, its API and export format when available. It follows that a high quality documentation will only be of use if and when the developer is stuck when guessing the meaning of a data field.
The recommendations for an Open Format targeting developers using forges is therefore to focus on (in that order):
- Theme: Cleanup: ensure F3 exports are published only if they validate against a well documented schema. When the schema changes, ensure it is backward compatible. When a new F3 schema is not backward compatible the data should be published in the old schema and the new schema during a period of time that allows developers to update the software.
- Theme: Documentation: a detailed documentation should be written for each F3 version. It should be included, for the most part, within the schema describing the data to facilitate the maintenance. The research does not show how and when the documentation is used. Data about the documentation usage should be collected after it is published.
- Theme: Modification history: the forge exports should be made available in VCS repositories so their modification history is published as well as their content.
- Theme: Format: publishing the data in a single, well documented format is OK because developers always convert the dataset they download into another format. Even when they are available in multiple formats.
Analisys of forge features
Auditing the features published by the two dominant software forges
provides insights about what F3 needs to support to help developers move from one forge to another.
Plans for the next month
- Use the F3 CLI, as a standalone tool or embedded in Forgejo, to continue the debug loop that integrates user feedback