pixelzoom
commented
3 years ago From https://github.com/phetsims/natural-selection/issues/275#issuecomment-828636620, below is the latest migration guide that @zepumph @samreid and I came up with for NS 1.3.
To conver Diff Wrapper "Breaking Changes" output to this format, we manually:
- grouped/collapsed related changes
- documented each group with a comment that summarizes the change
- documented each group with a GitHub issue number, for confirmation about when/why the change was made
Questions to discuss:
- We're not sure if the GitHub issue number should be shared with clients, but it's very useful internally for PhET.
- Is it sufficient that the title is "1.2 -> 1.3", or should it be more specific, like "1.2.1 -> 1.3.0" ? I suspect the latter. I forsee (e.g.) "1.3.0 -> 1.3.1", because there is definitely the possibility of API changes being introduced by maintenance releases.
Natural Selection 1.2 -> 1.3 Migration Guide
// model visibleProperty is now passed to view.
// See https://github.com/phetsims/natural-selection/issues/262
naturalSelection.introScreen.view.graphs.populationNode.populationGraphNode.dataProbeNode.visibleProperty.phetioTypeName changed from PropertyIO<BooleanIO> to LinkedElementIO
naturalSelection.labScreen.view.graphs.populationNode.populationGraphNode.dataProbeNode.visibleProperty.phetioTypeName changed from PropertyIO<BooleanIO> to LinkedElementIO
// Removed useless IOType, use parent instead.
// See https://github.com/phetsims/sun/issues/558
naturalSelection.introScreen.view.timeControlNode.fastForwardButton.phetioTypeName changed from RoundMomentaryButtonIO to NodeIO
naturalSelection.labScreen.view.timeControlNode.fastForwardButton.phetioTypeName changed from RoundMomentaryButtonIO to NodeIO
// Used to extend ReferenceIO but now uses IOType.supertype.
// See https://github.com/phetsims/tandem/issues/211
AlleleIO parameter types changed from ObjectIO to . This may or may not be a breaking change, but we are reporting it just in case.
GeneIO parameter types changed from ObjectIO to . This may or may not be a breaking change, but we are reporting it just in case.
// environmentPanel was added as a parent element.
// See https://github.com/phetsims/natural-selection/issues/263
naturalSelection.introScreen.view.environmentNode moved to naturalSelection.introScreen.view.environmentPanel.environmentNode
naturalSelection.introScreen.view.environmentRadioButtonGroup moved to naturalSelection.introScreen.view.environmentPanel.environmentRadioButtonGroup
naturalSelection.introScreen.view.generationClockNode moved to naturalSelection.introScreen.view.environmentPanel.generationClockNode
naturalSelection.introScreen.view.playButtonGroup moved to naturalSelection.introScreen.view.environmentPanel.playButtonGroup
naturalSelection.labScreen.view.environmentNode moved to naturalSelection.labScreen.view.environmentPanel.environmentNode
naturalSelection.labScreen.view.environmentRadioButtonGroup moved to naturalSelection.labScreen.view.environmentPanel.environmentRadioButtonGroup
naturalSelection.labScreen.view.generationClockNode moved to naturalSelection.labScreen.view.environmentPanel.generationClockNode
naturalSelection.labScreen.view.playButtonGroup moved to naturalSelection.labScreen.view.environmentPanel.playButtonGroup
// pickableProperty has been replaced with inputEnabledProperty.
// See https://github.com/phetsims/scenery/issues/1158
. . .
// opacityProperty has been uninstrumented.
// See https://github.com/phetsims/scenery/issues/1158
. . .
// PressListener pressAction and releaseAction became phetioReadOnly: true.
// See https://github.com/phetsims/scenery/commit/3bf7cb79e5aeb72ef30055c28759d151c62c66b5
. . .
// ObservableArray events and methods were replaced with Emitters.
// See https://github.com/phetsims/axon/issues/330
ObservableArrayIO is missing event: itemAdded, please use elementAddedEmitter
ObservableArrayIO is missing event: itemRemoved, please use elementRemovedEmitter
Method missing, type=ObservableArrayIO, method=addItemAddedListener, please use elementAddedEmitter
Method missing, type=ObservableArrayIO, method=addItemRemovedListener, please use elementRemovedEmitter
Method missing, type=ObservableArrayIO, method=getLength, please use lengthProperty
// phetioEngine methods were converted to Emitters.
// See https://github.com/phetsims/phet-io/issues/1655
Method missing, type=PhetioEngineIO, method=addPhetioElementAddedListener
Method missing, type=PhetioEngineIO, method=addPhetioElementRemovedListener
Method missing, type=PhetioEngineIO, method=addPhetioElementsBaselineListener
Method missing, type=PhetioEngineIO, method=addTypesAddedListener
Method missing, type=PhetioEngineIO, method=endEvent
Method missing, type=PhetioEngineIO, method=startEvent
// Input.js mouseDownAction parameter signature was changed to support iframe fix.
// See https://github.com/phetsims/natural-selection/issues/264.
naturalSelection.general.controller.input.mouseDownAction.phetioTypeName changed from ActionIO<Vector2IO, EventIO> to ActionIO<NullableIO<NumberIO>, Vector2IO, EventIO> changed a parameter
zepumph
samreid
kathy-phet
KatieWoe
While working on https://github.com/phetsims/natural-selection/issues/275, the output from the diff wrapper is too verbose, redundant and technical to be useful to a client hoping to update from 1.2 to 1.3. The diff wrapper has no way of knowing things like "we now use inputEnabledProperty instead of pickableProperty". Yet there are 263 lines like this in the breaking API diff:
We have been talking about sharing the diff wrapper as a guide to help our clients migrate from 1.2 to 1.3, but the changes are so numerous and technical that I don't recommend it. Instead, I think we should prepare a hand-written "migration guide" using the diff wrapper to help us make sure we cover everything. The migration guide can be shared via email for now. In the future we may want a place to publish migration guides. It would be best and most efficient to commit and track the migration guide in the sim repo, however, I think it will need to be committed elsewhere for the same reason we commit client-guides and reference API files elsewhere. phet-io-client-guides seems like the most natural repo, since it a guide for clients to migrate, but I have no familiarity with that repo, so I'm not confident about that.
This work can be done in master and does not need to be published in the natural selection RC. I should also mention, I don't think this needs to be perfectly refined, but (a) the rough draft is already much better than the diff wrapper and (b) we can use this case to think through how we will want to solve this problem in the future.
I'll mark it for discussion Thursday, though @zepumph and I may have an opportunity to talk about it in advance on Wednesday.