TAG Meeting 2020-02-12

Owned by Eric Jansson
Last updated: Feb 19, 2020

Particpants

  • Gary Johnson
  • Rosh Dhanawade
  •  J. Pablo Rodriguez
  • Geoff McElhanon
  • Thomas Christensen
  • Jim McKay
  • Lee Barber
  • Marcos Alcozer
  • Andrew Rice
  • Skyward Inc. - Josh Reimer
  • Britto Augustine
  • Jennifer Downey
  • Eric Jansson 
  • Chris Moffatt 

Materials

Notes

The agenda focused on the problem of how to release the Course Transcript SIG changes, but the SIG was asked to consider the question within the larger context of the cycles of releases, including questions such as how often to make major or breaking releases. The following attempts to summarize the TAG's opinion into a statement, but this statement must necessarily not be seen as endorsed by wholly by members; it is a starting point.

TAG Input on Release of Breaking Changes

The TAG felt that in the context of significant or breaking changes to an API and domain, the better option was to release a revised API in a separate namespace (which corresponds to a set of domain extensions in the ODS/API) and deprecate the current API (this is option #2 from the TAG meeting deck). There were a variety of reasons that TAG members voiced to justify this preference:

  • It allows a solution to get to market and be tested more quickly. This supports more rapid iteration towards a solution. However, on this point the TAG also cautioned that the solutions proposed need to be carefully researched and believed to work from available field evidence (e.g. this is not a context for A/B testing, etc.), as the new API is a material ask to some segment of the community
  • It is more standard in the software industry to deprecate and allow migration over time rather than to create "hard" transitions within a product release cadence.
  • It has benefits to internal or community development efforts, as it allows those to also factor in changes over time, creating opportunities for efficiency and stability.
  • It can allow for slow evolution over major updates.

On this last point, it was noted that major updates can be hard to consume and that the preference was for smaller updates on a regular cycle, likely annually.

The possible weakness of the strategy was that this strategy may be better for current community members rather than newcomers, as a newcomer will be given a "patched" version of the software and forced to migrate data when upgrading, rather than to be given the new, fixed version right from the start. It was noted that if the Ed-Fi data model and technology could be refactored into independent domains that might offer a solution where a new implementation could opt for the latest version (instead of a namespaced one), but that possibility has not been explored in any detail and so is theoretical only.

In pursuing this strategy of introduction, deprecation and migration, the TAG advised several mitigations be investigated:

  • Provide data migration supports for the movement from the deprecated domain / API back to the revised core domain / API
  • Reflect the presence of multiple overlapping but different (deprecated vs new) APIs in Swagger (or similar) documentation and UIs
  • Look into SDK supports that can help enable the transitions between deprecated and core models