PhET-iO Instrumentation checklist

[samreid]

From #64

Before instrumenting

• Copy this checklist to the issue description (top issue comment) for tracking. Link back to this checklist via /blob/<SHA>/ so that the specific guide you used is preserved. https://github.com/phetsims/phet-io/blob/b6303f013f9571158fe46a9e4b98b1382f35dd91/doc/how-to-instrument-a-phet-simulation-for-phet-io.md
• Understand the goal
• Create a dev release before beginning. This creates a benchmark to reference against for memory-leaks, sim size, performance, etc.
• Review the Code
• Keep tips and tricks in mind as you instrument
• Have a PhET-iO design meeting for the simulation to identify what should be customizable/interoperable/data stream. For example, see how-to-design-phet-io-features-for-a-simulation.md

The instrumentation Process

• Import Tandem to main.js
• Create root tandem
• Pass tandems to sim screens
• Pass tandems to model and view
• Add 'phet-io' as a supportedBrand in the sim's package.json, then run grunt generate-data in perennial (and check in changes under perennial/data), then you can use phetmarks to load wrappers for testing.
• Pass tandems to all constructors defined by the simulation
  • See also Testing while adding Tandem instances. Test with ?phetioValidateTandems=false since some common code-components don't yet have tandems.
• Pass tandem instances to common code components
  • See also Testing while adding Tandem instances.
• Create static tandems where appropriate.
• Instrument any uninstrumented common-code components used by the sim
• Instrument new component types defined by the sim
• IO Types should use proper inheritance
• Add simulation specific support
• Support dynamic state
• Test for memory leaks

After instrumenting

• Make sure Joist dt values are used instead of Date.now() or other Date functions. This is necessary for reproducible playback via input events.
• Are random numbers using phet.joist.random, and all doing so after modules are declared (non-statically)? For example, the following methods (and perhaps others) should not be used: Math.random, _.shuffle, _.sample, _.random.
• undefined values cannot be saved by phet-io, sims should be written to use null instead.
• Verify that the simulation works in all of the phet-io wrappers.
• Build with grunt --brand=phet-io and test the built version by launching build/wrappers/index and testing all the links.
• Manually look through Instance Proxies to make sure that tandems work as expected and are formatted correctly.
• Perform a full test for memory leaks. The benchmark dev release can be helpful here. This will help catch faulty tandem disposal.
• If the instrumentation process was large enough, then there is reason for another code review (or partial). Use your judgement. Ask @ariel-phet or @kathy-phet if you are worried about the cost.
• Set up a task to have the newly instrumented sim dev tested by the QA team.
• Update these instructions if you find them to be incomplete, inconsistent or incorrect.
• After publishing, add your instrumented simulation to the spreadsheet here: https://docs.google.com/spreadsheets/d/1pU9izdNQkd9vr8TvLAfXe_v68yh-7potH-y712FBPr8/edit#gid=0
• In conclusion

[samreid]

Everything complete or moved to new issues, closing.