CT Designed API changes detected, please roll them back or revise the reference API

[KatieWoe]

This issue has been in CT since about the time https://github.com/phetsims/QA/issues/657 was made, as pointer out by @pixelzoom on Slack. After a brief discussion with @kathy-phet we decided to hold on the rest of that RC until this could be looked at.

gravity-and-orbits : phet-io-api-compatibility : unbuilt
https://bayes.colorado.edu/continuous-testing/ct-snapshots/1624455729738/gravity-and-orbits/gravity-and-orbits_en.html?continuousTest=%7B%22test%22%3A%5B%22gravity-and-orbits%22%2C%22phet-io-api-compatibility%22%2C%22unbuilt%22%5D%2C%22snapshotName%22%3A%22snapshot-1624455729738%22%2C%22timestamp%22%3A1624457363837%7D&ea&brand=phet-io&phetioStandalone&phetioCompareAPI
Query: ea&brand=phet-io&phetioStandalone&phetioCompareAPI
Uncaught Error: Assertion failed: Designed API changes detected, please roll them back or revise the reference API:

gravityAndOrbits.general.model.simInfo._data.initialState differs. Expected: {"dataStreamVersion":"1.0.0","flags":null,"phetioCommandProcessorProtocol":"1.0.0","randomSeed":null,"referrer":null,"repoName":"gravity-and-orbits","screenPropertyValue":"gravityAndOrbits.homeScreen","screens":[{"name":"Home","phetioID":"gravityAndOrbits.homeScreen"},{"name":"Model","phetioID":"gravityAndOrbits.modelScreen"},{"name":"To Scale","phetioID":"gravityAndOrbits.toScaleScreen"}],"simName":"Gravity and Orbits","simVersion":"1.5.0-dev.8","url":null,"userAgent":null,"window":null,"wrapperMetadata":null}, actual: {"simName":"Gravity and Orbits","screens":[{"name":"Home","phetioID":"gravityAndOrbits.homeScreen"},{"name":"Model","phetioID":"gravityAndOrbits.modelScreen"},{"name":"To Scale","phetioID":"gravityAndOrbits.toScaleScreen"}],"simVersion":"1.6.0-dev.0","repoName":"gravity-and-orbits","screenPropertyValue":"gravityAndOrbits.homeScreen","wrapperMetadata":null,"dataStreamVersion":"1.0.0","phetioCommandProcessorProtocol":"1.0.0","randomSeed":null,"url":null,"userAgent":null,"window":null,"referrer":null,"flags":null}
Error: Assertion failed: Designed API changes detected, please roll them back or revise the reference API:

gravityAndOrbits.general.model.simInfo._data.initialState differs. Expected: {"dataStreamVersion":"1.0.0","flags":null,"phetioCommandProcessorProtocol":"1.0.0","randomSeed":null,"referrer":null,"repoName":"gravity-and-orbits","screenPropertyValue":"gravityAndOrbits.homeScreen","screens":[{"name":"Home","phetioID":"gravityAndOrbits.homeScreen"},{"name":"Model","phetioID":"gravityAndOrbits.modelScreen"},{"name":"To Scale","phetioID":"gravityAndOrbits.toScaleScreen"}],"simName":"Gravity and Orbits","simVersion":"1.5.0-dev.8","url":null,"userAgent":null,"window":null,"wrapperMetadata":null}, actual: {"simName":"Gravity and Orbits","screens":[{"name":"Home","phetioID":"gravityAndOrbits.homeScreen"},{"name":"Model","phetioID":"gravityAndOrbits.modelScreen"},{"name":"To Scale","phetioID":"gravityAndOrbits.toScaleScreen"}],"simVersion":"1.6.0-dev.0","repoName":"gravity-and-orbits","screenPropertyValue":"gravityAndOrbits.homeScreen","wrapperMetadata":null,"dataStreamVersion":"1.0.0","phetioCommandProcessorProtocol":"1.0.0","randomSeed":null,"url":null,"userAgent":null,"window":null,"referrer":null,"flags":null}
at window.assertions.assertFunction (https://bayes.colorado.edu/continuous-testing/ct-snapshots/1624455729738/assert/js/assert.js:25:13)
at XMLHttpRequest.<anonymous> (https://bayes.colorado.edu/continuous-testing/ct-snapshots/1624455729738/phet-io/js/phetioEngine.js:321:23)
id: Bayes Chrome
Snapshot from 6/23/2021, 7:42:09 AM

[samreid]

I committed an update to master to update the referenceAPI with the new version number. This doesn't cause any problems for the RC. The reason the version appears in the API file is discussed in https://github.com/phetsims/gravity-and-orbits/issues/386. This issue seems safe to close.

[pixelzoom]

Reopening.

@samreid said:

The reason the version appears in the API file is discussed in #386.

That issue doesn't tell me much. Is "version" the API version or the sim version? It was originally named simVersion. But in phet-io/api/natural-selection.json, I see:

  "version": {
    "major": 1,
    "minor": 0
  }

... which does not match the sim version at all, so leads me to believe that it's an API version. But GAO had to be updated to match the sim version.

So to help me understand "version" and this problem, I have many questions:

• What are the semantics of "version" in the API file?
• When does "version" need to be updated in the API file?
• How is "version" updated in the API? Manually? Build tools?...
• Why did this problem occur for GAO?
• Why did it occur around the time of publishing the RC?
• Why did you need to manually update version to 1.6.0-dev.0? Should that have been done by build tools?
• If version matches package.json for GAO, why is that not the case for Natural Selection?

[samreid]

I recommend discussing these points in https://github.com/phetsims/gravity-and-orbits/issues/386. I'll move them and comment there. @pixelzoom can this issue be closed?

[pixelzoom]

👍🏻 closing