Provide a way to test description changes without having to commit and push changes

[samreid]

At today's core design meeting, we discussed that for designers to make changes to the description using launchpad, they must first commit and push the changes. I demonstrated that we can use GitHub codespaces with a streamlined repo like https://github.com/phetsims/bundle-pack-aero in order to edit and test interactively, with the bonus that LLMs are provided in codespaces for more sophisticated changes. There was some concern that codespaces or vscode may be too sophisticated of an environment, but @brettfiedler said that with guidance it would be usable by all our team designers.

@brettfiedler advocated in particular for designers to have a local copy of the code, as he, @terracoda and @matthew-blackman have previously done. @arouinfar said that was troublesome in the past due to breaking changes to the tooling or setup. In discussion with @zepumph, he indicated that now that we have grunt sync that particular problem is significantly simplified, and @zepumph also surmised about a setup like https://github.com/phetsims/bundle-pack-aero, that we could use actual sub-repos (instead of sub-trees). I would like to experiment with this, as it could streamline our usage for both Codespaces and local copies. I would also like to experiment with some learnings from https://github.com/phetsims/bundle-pack-aero, like optimized npm scripts, postinstall scripts, and not having to have grunt installed as a global (which conflicted with @terracoda's permissions when she was using a npm setup outside of nvm).

In experimenting with a new container, we will have to consider:

• How much is it meant to scale? Is it for "a few repos at a time" or possible for all possible repos? Will grunt sync be ok with a subset? Will we need npm run tasks to add more? Do we want to have just 1 that can do everything, or multiple?
• Should this actually be a part of perennial/
• Will designers and developers share codespaces?
• Will we use phetsims codespaces (paid, at $0.18/hr) or personal forks (120 hours/month free)?
• How to streamline for designer usage. How to make commits/reverts/etc. How to describe what LLMs are capable of vs not?
• Should a new container repo be public or private? If it is public, it could help with the open source ecosystem, clients could use it to get started working with phet simulation code. If it is public, it will be possible for team members to fork for 120 hours/month of free Codespaces hours, and we can avoid team billing. Keeping it private may be good until it is more "ready to go" though. But in my experience with https://github.com/phetsims/bundle-pack-aero I did not have permission to change it from private to public.

[samreid]

I will try creating a harness in https://github.com/phetsims/umbrella. I have made it public for now, for the reasons listed above, and will give it a restrictive license. We can optionally make it private or delete it after discussion at the next designer meeting.

[samreid]

From discussion with @brettfiedler:

Existing strategies/prototypes/proposals:

1. subtrees (bundle pack aero)
   • acts like a monorepo
2. full-fledged repo clones (umbrella)
3. something more build-centric, like string-harness
4. designers clone git repos locally

@brettfiedler and I spent most of our time talking about the latter. Many/all of these points are from @brettfiedler:

• doesn't need us to maintain another "product"
• designers can iterate on SVG files.
• it may be daunting at first, but designers will learn how to use it.
• designers can adjust constants or colors. Imagine if you didn't have to "give the colors to a developer" to change it. You could just change it. There are some "easy" things that fall to the designer, and we can eliminate the "developer" part of that loop for certain tasks.
• you do not need to become a developer. you do not need to know how to do everything all at once. You can start with the basics, and learn other skills as needed.
• BF coordinated with a local LLM agent to make more sophisticated changes. Like adding more threshold levels to the description. The efficiency can be greater here.
• BF was good at branching, stashing, etc. Most designers won't want to do anything with merges.

The main steps to get started are:

• Install git
• Install nvm => node/npm
• Install an IDE. VSCode or IDEA. VSCode has copilot integrated. @samreid says both VSCode and IDEA are intimidating.

Other concerns:

• Would codespaces do these steps?
• how does it relate to rosetta?
• should LLMs be able to work on it?
• temporary vs permanent - we leaned toward more "reusable" containers that may have a longer startup time.

Should we improve our existing tooling, make it faster, more stable, better on windows? Add commands to streamline new use cases, like:
// only for a subset of repos
grunt sync-sim --sim=circuit-construction-kit

[samreid]

I labeled this for discussion at designer meeting Wednesday and do not have more plans to work on it at the moment, self-unassigning until then.

[brettfiedler]

Adding a draft version of the setup and command notes I previously had and have remade:

# PhET Designer in IDE Notes

## Daily Commands from the Sim Directory

- `cd your-current-sim` to navigate to your current sim directory.
- `grunt sync` or `grunt sync --slowPull` to sync your local copy of the code with the latest version on GitHub.
- `grunt dev-server` to start a server to view sims.
- Open `http://localhost:80/launchpad`

## Useful Commands from the Sim Directory

- `grunt modulify` for string and image files.
- Commit your changes to GitHub without using the web interface:
  1. `git pull` to pull the latest changes and make sure there are no conflicts. 
  2. `git add .` to add all changes to the staging area.
  3. `git status` to check the status of your local repository.
  4. `git commit -m "Your commit message"` to commit changes with a message.
  5. `git push origin main` to push your changes to the main branch of the repository.
- `cd ..` to navigate back one directory up.

## Helpful Commands for Saving and Discarding Local Changes in the Sim Directory

- `git stash` to save changes so you can check out the latest version of the code.
- `git stash pop` to reapply the saved changes.
- `git checkout --` to discard changes in your working directory.
- `git status` to check the status of your local repository.

## More Advanced Commands for Saving and Merging Local Changes in the Sim Directory

- `git checkout -b <branch-name>` to create a new branch and switch to it.
- `git checkout <branch-name>` to switch to an existing branch.
- `git merge <branch-name>` to merge changes from another branch into the current branch.
- `git rebase <branch-name>` to rebase the current branch onto another branch.

## Useful Sim Files and Their Typical Locations

- **Fluent File:** `../sim-name/sim-name-strings_en.yaml`
- **Colors File:** `../sim-name/js/common/SimNameColors.ts`
- **Query Parameters File:** `../sim-name/js/common/SimNameQueryParameters.ts`
- **Constants File:** `../sim-name/js/common/SimNameConstants.ts` or `../sim-name/js/screen-name/SimNameConstants.ts`
- Images: `../sim-name/images/`
  - License and Asset Attribution: `../sim-name/images/license.json`
    - For example,   
    
    ```
    "skateboard.svg": {
    "text": [
      "Copyright 2024 University of Colorado Boulder"
    ],
    "projectURL": "https://phet.colorado.edu",
    "license": "contact phethelp@colorado.edu",
    "notes": "created by Amanda McGarry"
    },
    ```

- Sounds: `../sim-name/sounds/`
  - (see license.json notes above) 
- Assets: `../sim-name/assets/`
- Documentation: `../sim-name/doc/`
   - Model.md: `../sim-name/doc/model.md`
   - Release Notes: `../sim-name/doc/releaseNotes.md`

## First Time Setup (SKIP ME IF USING CODESPACES)

1. [Install **Git**](https://git-scm.com/install/) (a tool for downloading code that we will connect to GitHub). 
   - On macOS, it’s easiest to install Git by [setting up Xcode command-line tools](https://git-scm.com/install/mac#:~:text=port%20install%20git-,Xcode%20Command%20Line%20Tools,-Apple%20ships%20a).
2. [Install Node.js and npm](https://nodejs.org/en/download) (tools for managing code and its dependencies). 
   - If you run into trouble with Node, consider using [**nvm** (Node Version Manager)](https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/) to help install and manage different versions of Node.js.
3. We'll be using an **IDE** (Integrated Development Environment) as well as a command line which we can access from that software. We recommend using [Visual Studio Code](https://code.visualstudio.com/download). 
   - !!! This is not what our developers use, but it is popular and well integrated with Copilot and has a simple-enough interface.
4. After installing, run these commands in the "Terminal" tab of the IDE:
   - `npm config set save false`
   - `npm config set package-lock false`
   - `git config --global user.name "PhET Girl"`
   - `git config --global user.email "phetgirl_github_account_email@example.com"`
5. Install a tool called **Grunt** (software used to automate tasks) by running: `npm install -g grunt-cli`.
6. Make a folder (directory) for the sims:
    - `mkdir phetsims` "make directory" (this will default to your home directory, but you can specify a different location if you want. Navigate using `cd` or "change directory").
7. Move into the directory you just made: `cd phetsims`
8. Clone our "perennial" repository:
    - `git clone https://github.com/phet/perennial.git`.
9.  Install dependencies for the "perennial" repository:
    - `cd perennial`
    - `npm install`
10. Install all the other repositories:
    - `grunt sync` or `grunt sync --slowPull` (this will take a while the first time, go do something else).
11. Move into your sim directory: `cd ../your-current-sim` and `grunt dev-server` to start a server to view sims!

[brettfiedler]

Based on the feedback from the meeting, I suspect this is not immediately needed. I suspect the topic will arise again, and should be brought up again if discussion around a tool to support this kind of iteration comes up.

I think we should mark deferred with a reminder to check in on it in 6 mo - 1 year to close if no longer relevant. I'll set a timed TODO for myself, but leaving unassigned.

[terracoda]

I asked a question in the meeting about how a designer can get to the YAML/Fluent file as early as possible in the design/implementation process to try to limit how-long we spend in there or even if there is a way to by-pass the google design doc for description design.

I personally do not like using the tables to lay out descriptions, and I feel that as designers get more advanced in their description design skills they will out grow the design doc as it is now as well.

I am interested finding a different description design flow that is much closer to the implementation side of the equation.