BREAKING CHANGES

[samrreid]

PhET APIs are constantly evolving and improving. That sometimes means making changes that are not backward compatible. We know that 3rd-party developers are using our libraries, and breaking changes are a drag - especially if you don’t know about them! So in this thread, PhET will post notifications of breaking changes to our APIs.

Sam Reid

PhET Interactive Simulations

University of Colorado Boulder

[Michael Kauzmann]

Use `DOT/dotRandom` as a module instead of the global `phet.joist.random`:

On 01/22/21, a refactor of joist's random object was done, moving the singleton to a module in dot/. Please use "dotRandom" as your random object (which is seeded for reproducibility). 

See https://github.com/phetsims/joist/issues/685 for details.

Michael Kauzmann

PhET Interactive Simulations
University of Colorado Boulder  

[Jonathan Olson]

Repository names have incompatibilities with npm if they aren't lower-case, so we're not able to currently support repo names with upper-case letters or spaces due to how NPM seems to be working. See https://github.com/phetsims/chipper/issues/1014#issuecomment-806228222 for details.

-Jonathan Olson

[Jonathan Olson]

We've adjusted our toolchain so that it prevents creating simulations with non-working repo names. Additionally, our grunt commands will expect repo names that fit the pattern (as many of them were failing anyway). See https://github.com/phetsims/chipper/issues/1034 for details.

-Jonathan Olson

[samrreid]

After pulling this commit in chipper https://github.com/phetsims/chipper/commit/76b08aaea48ad2b17db3f3cf1fe3339e34140cd5, you will need to run npm update in chipper due to a changed dependency, before builds will work properly.  Details are in https://github.com/phetsims/chipper/issues/1044

Sam Reid

PhET Interactive Simulations

[samrreid]

This change is not breaking, but an announcement that may be helpful.  After pulling perennial, you can npm update in perennial to get rid of a winston logging error message.  Details are in https://github.com/phetsims/perennial/issues/201

Sam Reid

PhET Interactive Simulations

[Jesse Greenberg]

This commit in joist on 6/23/21 changed the parameters of some layout functions in joist. This involves JOIST/ScreenView.js and any popups added to JOIST/Sim.js with "showPopup". Layout functions now take a Bounds2 instead of width/height values. If you implement or override these functions they will need to be updated after pulling this change. For more information, please see https://github.com/phetsims/joist/issues/723.

Jesse Greenberg

PhET Interactive Simulations

[samrreid]

As part of https://github.com/phetsims/chipper/issues/1033, I've added a new eslint rule called "consistent-return", which is described in https://eslint.org/docs/rules/consistent-return.  If you don't opt out, after you pull chipper, this lint rule will be enforced on your code.  It's been a helpful rule, and helped us identify several bugs.  Good luck!

Best Regards,

Sam

PhET Interactive Simulations

[cmalley]

As part of https://github.com/phetsims/bamboo/issues/38, bamboo's AxisNode was renamed to AxisArrowNode.  If you were using AxisNode in your code, you will need to rename.  And if you'd have an axis that does not need arrows, you can now use the new AxisLine.

Chris Malley

PixelZoom, Inc.

[samrreid]

As part of https://github.com/phetsims/chipper/issues/1018, we have introduced "annual", which is a versioned clone of "perennial".  Please run a clone missing repos script at your convenience, and you may wish to exclude one or the other of annual/perennial (but not both) from your IDE.

[samrreid]

Please note this means you will need to run npm install/npm update commands in annual.

[samrreid]

UPDATE: We have renamed "annual" to "perennial-alias", so the prior 2 comments should refer to that.  Also, we may remove that pattern altogether if an alternate proposal pans out.

[samrreid]

PhET is transitioning to TypeScript, please see: https://groups.google.com/g/developing-interactive-simulations-in-html5/c/VCAUC6nhI6Q

[samrreid]

During conversion to TypeScript, we created some module import cycles in scenery.  Hence, we've had to transition to an import style like:

import { Node } from '../../../scenery/js/imports.js';
import { Rectangle } from '../../../scenery/js/imports.js';
import { RichText } from '../../../scenery/js/imports.js';

At the moment, this style is only necessary when importing from scenery.  There is now also a lint rule to prevent the prior style.

More details are available at https://github.com/phetsims/scenery/issues/1324.  

Best Regards,

Sam Reid (PhET Interactive Simulations)

[Michael Kauzmann]

During our conversion to Typescript, we have deprecated our previous enumeration pattern. This means Enumeration.js was renamed to EnumerationDeprecated.js. The newly-created Enumeration.ts is part of a new pattern explained as the primary pattern in https://github.com/phetsims/phet-info/blob/master/doc/phet-software-design-patterns.md#enumeration.


Please see https://github.com/phetsims/chipper/issues/1106 for details about the conversion.

Thanks,
Michael Kauzmann (PhET Interactive Simulations)

[samrreid]

As part of https://github.com/phetsims/joist/issues/844, we have changed the constructor of JOIST/Sim from `string | TReadOnlyProperty<string>` to `TReadOnlyProperty<string>`.  This is a breaking change that will require Sim constructor callers to use the latter.  To create a constant title, you can use `new Property('my title')`, importing `Property` from axon.  This will help our efforts in internationalization and PhET-iO.

Best Regards,

Sam

[samrreid]

For developers providing translations using the babel/ repo, there is a new process to test the translations in unbuilt mode.  Details in https://github.com/phetsims/chipper/issues/1308

There is a new step in our process to generate conglomerate translation files from babel.  `grunt generate-development-strings` in a repo will create that conglomerate file.  Run on all repos via:

for-each.sh perennial/data/active-repos grunt generate-development-strings

This is not run in grunt update because it affects dependencies and outputs files outside of the repo.This only affects the unbuilt strings, and prevents the 404s we have seen recently.

If you are not creating or providing new files in babel/ you can likely just `git pull` to get changes on a regular basis.

[samrreid]

After changes in https://github.com/phetsims/sun/issues/794, you can no longer specify node/tandem to AquaRadioButtonGroup and VerticalCheckboxGroup.  Instead, please use `createNode` and `tandemName`.

Thanks, and have a nice day!

Sam

[samrreid]

In https://github.com/phetsims/sun/issues/787 we committed an API breaking change. RectangularRadioButtonItem no longer uses node + tandem, it now uses createNode + tandemName.

[Michael Kauzmann]

In https://github.com/phetsims/axon/issues/425, NumberProperty's `range` option was changed to no longer accept `null` as a value. Now all NumberProperty instances have a defined range, defaulting to (-∞,∞). Thus NumberProperty.prototype.range and NumberProperty.prototype.rangeProperty.value will always be of type Range.

[Michael Kauzmann]

In https://github.com/phetsims/axon/issues/428, we removed the `ReadOnlyProperty.useDeepEquality` option because it was confusing and limited in scope. Instead, use `valueComparisonStrategy: 'eqaualsFunction' to reproduce the same functionality as `useDeepEquality`. 

[samrreid]

In https://github.com/phetsims/sun/issues/814, we have changed the public API for the sun Carousel. The changes help Carousel have better dynamic support, for adding and removing items.  The API change is that instead of accepting an array of Nodes, it accepts an array of CarouselItem.

[Michael Kauzmann]

In https://github.com/phetsims/scenery/issues/1472, we renamed the "text" related API to "string" when talking about the string that the node renders. This is for Text and RichText:

* The Node option `text` is now `string`
* getText() and setText() are now getString() and setString()
* es5 getters and setters for text are now string

Please report in that issue if you run into trouble.

[samrreid]

PhET is now using TypeScript 5.0, please see https://github.com/phetsims/chipper/issues/1384 for details.  Please pull chipper and npm install to get the new version.  After updating, you can run `cd chipper` then `node node_modules/typescript/bin/tsc --version` to see that your version updated correctly. Please report problems in the issue.

Thanks!

Sam

[Michael Kauzmann]

All PhET Github repos have been converted to use the "main" branch instead of the "master" branch.

This means that active development is now occurring on "main". To update your local copies, please follow these steps:

Here is what to do if you find yourself locally on the master branch for everything.

Make sure you have a clean, freshly pulled, working copy. If not stash any local changes and make sure you're pulled.
Run `perennial/bin/for-each.sh active-repos git checkout main; perennial/bin/for-each.sh active-repos git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main` to switch all active repos to the main branch. If you have other repos that are not in the list of active ones you can run this command instead (your mileage may vary): `for f in $(ls) ; do (cd $f; git pull ; git checkout main; git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main) ; done`.
Run `perennial/bin/for-each.sh perennial/data/active-repos "rm .git/hooks/pre-commit; git init --template=../phet-info/git-template-dir"` to update your git hooks to run on the "main" branch (if applicable).
Run `perennial/bin/for-each.sh active-repos git status` and make sure each says you're pointing to origin/main and not origin/master.

[samrreid]

Breaking Changes has been moved to https://github.com/orgs/scenerystack/discussions/9

For more information, see this post: https://groups.google.com/g/developing-interactive-simulations-in-html5/c/CyJPJoXnNv0