Merge pull request #151 from scenerystack/repo-sync/phet-info/default

brettfiedler · web-flow · commit 22da20eeb0f2 · 2025-05-14T12:11:09.000-04:00
🔄 synced file(s) with phetsims/phet-info
diff --git a/docs/info-sync/alternative-input-quickstart-guide.md b/docs/info-sync/alternative-input-quickstart-guide.md
@@ -55,10 +55,6 @@ Follow these steps to add support for alternative input to a simulation.
    See https://github.com/phetsims/phet-info/blob/main/doc/interactive-highlights-quickstart-guide.md for more
    information about this feature.
 
-4. Sims that support alternative input also need an accessible Preferences dialog. See
-   https://github.com/phetsims/phet-info/blob/main/doc/accessible-preferences-quickstart-guide.md for information about
-   this.
-
 ## Make a Node focusable
 
 Most common code UI components are already focusable. But you can make any Node focusable by using these options from
diff --git a/docs/info-sync/chipper-deploy.md b/docs/info-sync/chipper-deploy.md
@@ -7,6 +7,7 @@
 * [Building standalone repositories](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#building-standalone-repositories)
 * [Building wrapper repositories](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#building-standalone-repositories)
 * [Deploying simulations](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#deploying-simulations)
+  * [Running commands in perennial](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#running-commands-in-perennial)
   * [If working off campus, install the VPN](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#if-working-off-campus-install-the-vpn)
   * [Configure build-local.json settings](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#configure-remote-bashrc)
   * [Configure remote ~/.bashrc](https://github.com/phetsims/phet-info/blob/main/deployment-info/chipper-2.0.md#configure-remote-bashrc)
@@ -32,11 +33,6 @@ brands you would like to build by default).
 `grunt --brands=phet,phet-io` (using `--brands`) will override and build the desired brands. If any brand given like
 this is not supported, the build will fail out.
 
-Chipper 2.0 also adds the `--debugHTML` option to builds (will build another version with the `_debug` suffix), and has
-the `-allHTML` option (not relevant for the phet-io brand). Additionally, it is possible to build a sim with a one-off
-version identifier with `--oneOff={{ONE_OFF_NAME}}`, which will be included in the version identifier. This is a build
-flag, and is not provided to deployment tasks.
-
 # Updating supported brands
 
 In each sim's package.json, it lists the brands that are supported. When a phet-io sim is instrumented, it should be
@@ -49,20 +45,16 @@ Scenery/Kite/Dot/etc. can be built as a standalone file that can be included (e.
 examples and documentation). Just `grunt` in the repository should do the trick, and note that there are no brands, so
 it does not create brand directories.
 
-# Building wrapper repositories
-
-Repositories like phet-io-wrapper-sonification can also be built with `grunt`, placing the files to be uploaded in the
-build directory.
-
 # Deploying simulations
 
 If you haven't run perennial commands in a while, `npm prune` and `npm update` under perennial, perennial-alias and
 chipper may be needed. I'll notify for any further module changes.
 
-Note that all perennial commands (including those for dev/rc/production deployments) can be run from newer (as of
-sometime December 2017) simulations from the simulation directory. For instance, `grunt checkout-shas` now lives in
-perennial, but newer chipper SHAs will detect this and spawn the correct perennial grunt task. It will add
-a `--repo={{REPO}}` command line flag to the perennial command so that it knows which repository is the target.
+## Running commands in perennial
+
+Note that all perennial commands (including those for dev/rc/production deployments) can be run from the simulation
+directory (post 12/2017). For instance, `grunt checkout-shas` now lives in perennial, and so it will add a
+`--repo={{REPO}}` command line flag to the perennial command so that it knows which repository is the target.
 
 So, for example,
 
@@ -76,6 +68,9 @@ will run
 perennial# grunt dev --repo=chains --brands=phet,phet-io
 ```
 
+You can always run these commands from perennial directly by just adding the `--repo={{REPO}}` option. Commands listed
+below that do not include the `--repo` option assume you are running from the simulation repo.
+
 ## If working off campus, install the VPN
 
 - If you work exclusively on campus, this step is not required.
@@ -84,8 +79,8 @@ perennial# grunt dev --repo=chains --brands=phet,phet-io
 
 ## Configure build-local.json settings
 
-Your default build configuration is specified in `~/.phet/build-local.json`. Describing or identifying the entries
-in `build-local.json` is beyond the scope of this document; ask a PhET developer for help in setting up this file. At a
+Your default build configuration is specified in `~/.phet/build-local.json`. Describing or identifying the entries in
+`build-local.json` is beyond the scope of this document; ask a PhET developer for help in setting up this file. At a
 minimum you will need `devUsername` and `buildServerAuthorizationCode`. A few handy keys:
 
 - `buildServerNotifyEmail`: add your email to be notified on the success or failure of your builds to the build server.
@@ -124,11 +119,11 @@ Configure an RSA key, or you will be prompted multiple times for a password duri
 
 - Add your public key (found in `localhost@~/.ssh/id_rsa.pub`) to `bayes@~/.ssh/authorized_keys`.
   - This can usually be accomplished by running `ssh-copy-id bayes`.
-  - If you don't have `ssh-copy-id`,
-    use `cat ~/.ssh/id_rsa.pub | ssh {{IDENTIKEY}}@bayes.colorado.edu "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"`
+  - If you don't have `ssh-copy-id`, use
+    `cat ~/.ssh/id_rsa.pub | ssh {{IDENTIKEY}}@bayes.colorado.edu "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"`
 - Change the permissions of `authorized_keys` so it is not group writable: `chmod g-w authorized_keys`
-- Test ssh from your local machine at least once so that you can accept the remote RSA key from bayes by
-  running `ssh bayes`.
+- Test ssh from your local machine at least once so that you can accept the remote RSA key from bayes by running
+  `ssh bayes`.
 
 ## Dev deployments
 
@@ -147,33 +142,35 @@ increment the version test number (e.g. the 2 in 1.3-dev.2). For example, if the
 
 ## One-off deployments
 
-These are like dev deployments, but should be done from a named branch (where the name does not contain any `-` or `.`
-characters).
+These are like dev deployments, but are done from a named branch that is not "main" (where the branch name does not
+contain any `-` or `.` characters). One-offs are useful to keep track of shas for maintenance or reproducibility, but
+are not a formal, versioned release.
 
-Prior to branch creation, be sure to create a GitHub issue within the associated repo. Its title should be of the
-form `branch: {{branchName}}`, and the description should describe the purpose of the branch, expected lifetime of the
+Prior to branch creation, be sure to create a GitHub issue within the associated repo. Its title should be of the form
+`branch: {{branchName}}`, and the description should describe the purpose of the branch, expected lifetime of the
 branch, and links to any other relevant issues.
 
-To create a branch (easily) for one-off deployments, run:
+To create a branch (easily) for one-off deployments run the following command from the exact SHAs that you want in your
+one-off. You may want to run `grunt checkout-target` first to create the one-off from a release branch instead of
+`main`.
 
 ```sh
 grunt create-one-off --branch={{BRANCH}}
 ```
 
-This will create the branch with the relevant name, and set up the package.json appropriately.
-
-Thus a normal `grunt` will build with the one-off version from the branch. To deploy a one-off version:
+This will create the branch with the relevant name, and set up the package.json appropriately. Thus a normal `grunt`
+will build with the one-off version from the branch. To deploy a one-off version:
 
 ```sh
-grunt one-off --brands={{BRANDS}}
+grunt one-off --brands={{BRANDS}} --branch={{BRANCH}}
 ```
 
-from the branch.
+This will checkout the branch and its dependencies, and deploy using the "dev" version deployment algorithm.
 
 ## RC/production deployments and release branches
 
-Chipper 2.0 release branches support building of all brands. The branch name will ONLY ever be of the
-format `{{MAJOR}}.{{MINOR}}`, e.g. `1.7`, and that branch will only support building/deploying versions that match that
+Chipper 2.0 release branches support building of all brands. The branch name will ONLY ever be of the format
+`{{MAJOR}}.{{MINOR}}`, e.g. `1.7`, and that branch will only support building/deploying versions that match that
 major/minor combination.
 
 NOTE: Release branches are created for RCs. If you need to make a change after the first RC (but before publication),
@@ -186,14 +183,13 @@ also deploy an RC (which is typical when creating the release branch), just run
 prompt you whether the release branch should be created. For example, if `1.6` was the latest release branch, and you
 want to create `1.7` and deploy an RC, just fire off `grunt rc --branch=1.7 --brands={{BRANDS}}`.
 
-If you do not want to deploy an RC when creating the release branch, instead directly
-do `grunt create-release --branch=1.7 --brands={{BRANDS}}` (which will handle all steps to create the new branch).
-Release branches should be created using either `grunt rc` or `grunt create-release`, as this sets them up with the
-correct package.json version and dependencies.json content.
+If you do not want to deploy an RC when creating the release branch, instead directly do
+`grunt create-release --branch=1.7 --brands={{BRANDS}}` (which will handle all steps to create the new branch). Release
+branches should be created using either `grunt rc` or `grunt create-release`, as this sets them up with the correct
+package.json version and dependencies.json content.
 
-NOTE: The `--brands` you include in the command will be set as the only supported brands for the release branch in
-the `package.json`. NOTE: It will initialize the branch to a version of 1.0.0-rc.0, and then increment/deploy to
-1.0.0-rc.1.
+NOTE: The `--brands` you include in the command will be set as the only supported brands for the release branch in the
+`package.json`. NOTE: It will initialize the branch to a version of 1.0.0-rc.0, and then increment/deploy to 1.0.0-rc.1.
 
 ### RC/production deployment on an existing branch
 
@@ -228,24 +224,24 @@ suite of sims in RC" section in automated-maintenance-process.md.
 If you want to make a change to the sim's own repo on the release branch (and no changes to other dependencies), then
 generally first do the following:
 
-- From perennial, `grunt checkout-target --repo={{REPO}} --target={{BRANCH}}`,
-  e.g. `grunt checkout-target --repo=chains --target=1.2`.
-- Apply the change to the sim's branch (either a usual commit, or by cherry-picking a change,
-  e.g. `git cherry-pick -x {{SHA}}` in the sim repo).
+- From perennial, `grunt checkout-target --repo={{REPO}} --target={{BRANCH}}`, e.g.
+  `grunt checkout-target --repo=chains --target=1.2`.
+- Apply the change to the sim's branch (either a usual commit, or by cherry-picking a change, e.g.
+  `git cherry-pick -x {{SHA}}` in the sim repo).
 - Test it. You can `grunt` in the sim repo (the `checkout-target` above did the NPM magic for it to work)
 - Push the change to the sim branch (e.g. `git push origin 1.2`).
 
 Otherwise if a dependency (e.g. scenery or any "common" repo) needs patching:
 
-- From perennial, `grunt checkout-target --repo={{SIM}} --target={{BRANCH}}`,
-  e.g. `grunt checkout-target --repo=chains --target=1.2`.
+- From perennial, `grunt checkout-target --repo={{SIM}} --target={{BRANCH}}`, e.g.
+  `grunt checkout-target --repo=chains --target=1.2`.
 - Check the common repo to see if it has a branch named `{{SIM}}-{{BRANCH}}`, e.g. does scenery have a branch named
   chains-1.2
   - If it HAS the branch, ensure that the branch's HEAD commit is the same as the currently-checked-out commit. THEN
     checkout the branch (e.g. `git checkout chains-1.2`) in the common repo. If the commits don't match, INVESTIGATE as
     something went wrong before. Talk to @jonathanolson?
-  - If there IS NO branch, create it in the common repo with `git checkout -b {{SIM}}-{{BRANCH}}`,
-    e.g. `git checkout -b chains-1.2`
+  - If there IS NO branch, create it in the common repo with `git checkout -b {{SIM}}-{{BRANCH}}`, e.g.
+    `git checkout -b chains-1.2`
 - Apply the change to the dependency's branch (it's almost always a cherry-pick, e.g. `git cherry-pick -x {{SHA}}` in
   the common repo).
 - Test it. You can `grunt` in the sim repo (the `checkout-target` above did the NPM magic for it to work)
diff --git a/docs/info-sync/simulation-development-overview.md b/docs/info-sync/simulation-development-overview.md
@@ -3,10 +3,11 @@
 ## Overview
 
 PhET Interactive Simulations creates free, open source educational simulations in science and math, which you can find
-at the PhET website. This document explains PhET’s libraries ([SceneryStack](https://scenerystack.org/), practices and patterns for developing interactive
-simulations in HTML5. This document is also available
-at https://github.com/phetsims/phet-info/blob/main/doc/phet-development-overview.md. For discussion and feedback, please
-visit the [SceneryStack Discussions forum](https://github.com/orgs/scenerystack/discussions).
+at the PhET website. PhET Interactive Simulations are created using the [SceneryStack](https://scenerystack.org/) web development libraries. This document explains the internal development process using SceneryStack libraries, and practices and patterns for developing interactive simulations in HTML5. 
+
+If you are developing a simulation, but are not working directly with PhET, please refer to the [SceneryStack documentation](https://scenerystack.org/learn/simulation/) for best practices developing simulations using the bundled NPM package.
+
+This document is also available at https://github.com/phetsims/phet-info/blob/main/doc/phet-development-overview.md.
 
 
 <!--@formatter:off-->
@@ -106,11 +107,8 @@ cd ../${directory of the sim you are working on}
 npm install
 ```
 
-### Transpile TypeScript
+###  TypeScript
 
-* Change directory to the build tools: `cd chipper/`
-* Run the TypeScript transpiler: `grunt transpile --all --live` which starts a process that will auto-transpile
-  when files change.
 * For more details about TypeScript, please
   see [PhET's TypeScript Quick Start Guide](https://github.com/phetsims/phet-info/blob/main/doc/typescript-quick-start.md)
 
@@ -131,11 +129,6 @@ npm install
   simulations: http://localhost:8080/example-sim/build/adapted-from-phet/example-sim_en_adapted-from-phet.html (port or
   path may depend on your HTTP server configuration)
 
-### Questions
-
-* Questions should be directed to
-  the [SceneryStack Discussions forum](https://github.com/orgs/scenerystack/discussions).
-
 ## Creating a New Sim
 
 After checking out the dependencies and installing grunt-cli in the preceding instructions, you can create your own
@@ -157,11 +150,10 @@ simulation using the template.
    `grunt create-sim --repo=NAME --author=AUTHOR`
    For instance, if the simulation is going to be named Acceleration Lab and the author is Jane Doe, then you could put:
    `grunt create-sim --repo=acceleration-lab --author="Jane Doe"`
-6. In your simulation directory, run the transpiler watch process and specify your new repo as a target:
+6. In your simulation directory, run the dev-server:
    `cd ../acceleration-lab`
-   `grunt output-js-project --live`
-7. Test the created simulation in the browser and make sure it launches. It should be a blank simulation. Write to the
-   [SceneryStack Discussions forum](https://github.com/orgs/scenerystack/discussions) if you run into problems.
+   `grunt dev-server`
+7. Test the created simulation in the browser and make sure it launches. It should be a blank simulation.
 
 ## Building and Testing
 
@@ -269,10 +261,16 @@ as common dependencies are changed.
 The main branch of the PhET simulation and library repositories is constantly under development and not guaranteed to be
 stable. It is our intent that the main branch of simulations + libraries will build and run properly, but sometimes the
 code goes through intermediate states where errors can be introduced. On the other hand, our published simulations have
-been rigorously tested across 18+ platforms and are the most stable option. If you are adapting a PhET simulation, or
-would like to access simulation code that corresponds directly to one of our published versions, then you will need to
-check out specific SHA revisions in all of the appropriate repositories. Checking out these fixed, tested revisions is
-also important when working on a release-candidate branch of a simulation. Here are the instructions:
+been rigorously tested across 18+ platforms and are the most stable option. 
+
+If you are building a simulation from scratch using [SceneryStack](https://scenerystack.org/learn/overview), 
+you will only need to worry about potential breaking changes when updating the NPM package to a newer version. 
+See [SceneryStack Versioning](https://scenerystack.org/community/versioning/) for more information.
+
+If you are adapting a PhET simulation, or would like to access simulation code that corresponds directly to one 
+of our published versions, then you will need to check out specific SHA revisions in all of the appropriate repositories. 
+Checking out these fixed, tested revisions is also important when working on a release-candidate branch of a simulation. 
+Here are the instructions:
 
 1. First, identify the version for which you want to check out the source code, for
    example: https://phet.colorado.edu/sims/html/area-builder/latest/area-builder_en.html
