Blog update (July 9, 2020): We created a fun and informative infographic to help you understand Ed-Fi versioning changes.
A New Version of Ed-Fi Versions
The transition of Ed-Fi to open source is bringing a few additional changes, and important among these are changes to the system used to version Ed-Fi software releases.
A New Version Number…
Going open source means moving from a more limited community context to a much broader context, one that will require a greater community effort to manage and coordinate.
Accordingly, the Alliance is shifting versioning to adopt an industry-standard versioning system called “semantic versioning” and as a result, you will see new version numbers start to appear on Ed-Fi software releases. The numbers will take this form:
MAJOR.MINOR.PATCH[-optional label]
Examples would be:
v4.0.1
v3.2.0-c
v1.8.0
Why make this change now? As mentioned above, the new context of open source is an opportune time to align to the stricter versioning practices followed by major open source projects, and most commercial products too. There are some concrete benefits to semantic versioning as well:
- Version numbers provide clear indications as to if the release will “break” anything, or if the release is a minor release
- As a side effect, the system will force us to define what “breaking” means for each product
- Version numbers will now signal if there is any “early access” material in the release (features that might not be production-ready, or are otherwise experimental)
The full details of the semantic versioning system can be found here: https://semver.org/
Ed-Fi Suites
As part of this change will also see slight changes in how some products are referred to. In the past, the Alliance could use the product major version number to indicate that products were part of the same Ed-Fi Suite, as in
Data Standard v3.1
ODS/API v3.2
The “3” here (underlined above) signaled that these were part of Suite 3, so part of the same generation of Ed-Fi technology.
However, with semantic versioning, we can no longer align major versions in this fashion (we must update the major version number when we break something), and so the suite name will appear next to the product name instead. The suite name will now indicate that elements are part of the same generation.
Data Standard for Suite 3 v3.2.0
ODS/API for Suite 3 v5.0.0
In the example above, even though the version numbers don’t look similar (3.2.0 vs 4.0.0), you can tell the releases are part of the same generation of technology via the suite info (underlined).
Not all products will show suite information in the same, as some span suites. If you ever need precise information on suite composition and compatibility, you can check the Ed-Fi Technical Suite Version Matrix.
When is This Happening?
This is a small but important change and will generally be rolling out for each product as those Ed-Fi products are moved to their new repo locations on GitHub under the Ed-Fi Open Source organization. (https://github.com/orgs/Ed-Fi-Alliance-OSS).
In the first place you will see this for the upcoming releases of the ODS/API and Admin App (currently scheduled for release in July). According to the previous versioning approach, these releases would have been identified as ODS/API v3.5 and Admin App v1.9. Under the new approach, the releases will be identified as ODS/API for Suite 3 v5.0.0 and Admin App for Suite 3 v2.0.0.
Also, please note that the intent is that these changes are forward-looking only; we will generally not modify older version numbers and the new numbers will generally start to appear in the new repo locations and documentation for new releases going forward.
