Improve high-level documentation about phetsims repos

[zepumph]

From https://github.com/phetsims/phet-io-wrappers/issues/292.

It was brought up that github repos have a flat structure, there is no inherent way to classify or organize them. The main issue with this is adding to the cognitive load of newcomers. There is no good way to understand high level groupings.

If we just had a single giant repo, it is likely that we would have a structure like:

• phetsims
  • common
  • sun
  • scenery-phet
  • sims
  • wave-interference
  • wrappers
  • classroom-activity
  • studio

But since we don't, and all repos are treated the same, we may want to work on our high level documentation of these repos.

@jonathanolson mentioned that we have package.json flags that serve similar purposes to this, and coalesce into lists in perennial/data, but I think we can improve further on this.

Marking for dev meeting at a low-ish priority per @ariel-phet's request.

[pixelzoom]

I don't think that having a single document is the way to go. It is unlikely to be maintained, and it's not "the way" that GitHub repositories are typically documented.

I'd start with a list of common-code repositories, and put useful information/overview in the README.md files for those common-code repositories. The README.md is what everyone sees when they come to a repository's GitHub page - it's where you'd expect to start learning about a repository.

PhET's common-code README.md files are relatively sparse and stale. For example, here's the substance of axon/README.md, one of PhET's most fundamental repos:

Axon provides powerful and concise models for interactive simulations, based on observable Properties and related patterns.

This provides almost no help to someone who needs an overview. What models? What related patterns? No info about what types of things are grouped here - nice that Property was (sort of) identified, but nothing here about Actions, Emitters, or validators. Etc.

[jonathanolson]

Improving READMEs of common repos sounds good in general.

[samreid]

Note this overlaps somewhat with the automatic README generation in https://github.com/phetsims/utterance-queue/issues/5#event-2971998130

[jessegreenberg]

We are going to wait until @ariel-phet is available to discuss this during a dev meeting, we need to decide which developers will be responsible for documentation in each repo.

[samreid]

We would like to discuss this further when @pixelzoom returns.

@ariel-phet pointed out that we have more outside users using phet code now. In order to help with onboarding, and making our libraries easy to use, steps forward here will be a bonus. We will probably make this a chip-away issue, but will wait until more devs are here to decide where to start.

[zepumph]

From today's developer meeting:

How to make breaking api changes like to SimLauncher and es6 module conversion? These changes supposedly broke TH's repo and he had to manually update things.

We discussed converting to semantic versioning, but felt like it was too much of a burden, and that we are quite set up to develop and publish on master.

• [ ] We think that it would be good to create a thread in the google group to let people know when we make breaking changes, perhaps called "Breaking Changes".

Other topics for this issue:

• High level documentation means "what do these repos mean" and how are things connected. How could that be improved on?
• @samreid pointed out that https://github.com/phetsims/phet-info/blob/master/doc/phet-development-overview.md#source-code-and-dependencies already has a list of repos and a brief explanation. Perhaps we can expand there.
• @brandonLi8 mentioned that expanding on each common code README file.
  • Link to the demo sun (scenery-phet or sun)
  • For sun right now, it says it runs on scenery, but perhaps a link to that.
• Update public scenery documentation because it is out of date.
• @pixelzoom said that TH was able to have success by primarily looking at other sims as examples. Instead of looking in sun for a slider, he looked for a usage of a slider and copied that over.
• @chrisklus making some sort of "tree graphic" for explaining the "org chart" of the repos.
  • @pixelzoom expanded on this with adding the MVC dimension, and perhaps a "layered" explanation as it pertains to API and functionality. For example scenery internal -> scenery Node -> common code Nodes -> Use in a ScreenView.
• It was mentioned that the names of repos is confusing and hard to remember.
• @zepumph mentioned that binder doc could be co-opted with a view that was helpful for displaying common code examples or available components.
• @chrisklus: This is not just good for onboarding, but instead as a constant reference that starting devs normally have to just keep asking senior devs (@zepumph agrees!).
• @ariel-phet: a graphic/tree should recognize responsibility, like how chipper and perennial are different (build tools) from other browser side
• @Denz1994: we should "pin" some things for our organization. We should pin phet-info, and maybe a gist file.
• @brandonLi8: we should make the example sim more complicated so that more learning can be accomplished.
  • @pixelzoom: what was missing, what would you like to add?
  • @brandonLi8: More development with Node, instead of just addChild.

[pixelzoom]

I seem to recall that this was assigned to me because I volunteered to do something. But I don't recall what it is, and I don't see it in the meeting notes above. @zepumph @ariel-phet can you refresh my memory?

[zepumph]

I don't recall at all. @ariel-phet is the guy.

[pixelzoom]

Ah, now I remember. I'm going to create a "BREAKING CHANGES" thread in the Google Group.

[pixelzoom]

I started writing the "BREAKING CHANGES" topic. It seems like this should be a message from PhET. So (as a vendor) it doesn't feel appropriate for me to start this thread.

Here's what I came up with for the title and text:

BREAKING CHANGES

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.

I would pin this topic to the top of the list - check the box to the left of the topic, then choose "Actions > Display at the top".

@ariel-phet please assign someone from PhET to start this thread. And it's fine with me if they want to modify my prose.

[ariel-phet]

@samreid could you start this thread on the google group (feel free to consult with @pixelzoom)

[samreid]

I posted the text @pixelzoom recommended, but I don't see any UI for pinning a message. It looks like this at the moment:

I confirmed I am a manager of the group, and I am logged in to the manager account. I also confirmed the metadata can be moderated in the settings, based on remarks in https://support.google.com/a/thread/4876075?hl=en

I can't tell if I am doing something wrong or if Google changed/removed the "Display at the Top" interface. If they removed this feature, should we just link to that thread from the group description?

[samreid]

Here is the old welcome message for our records:

Welcome to the Developing Interactive Simulations in HTML5 Google Group!  Developing complex, high-performance, interactive simulations in HTML5 that work well on many platforms is tricky business, and we thought this would be a nice place to discuss problems, solutions, strategies and ideas.

PhET Interactive Simulations is developing several open-source libraries to facilitate simulation development, and we have documented the libraries as well as patterns and practices that work well for us in our PhET Development Overview: https://github.com/phetsims/phet-info/blob/master/doc/phet-development-overview.md

Looking forward to hearing from you!

If I add

BREAKING CHANGES: please see https://groups.google.com/g/developing-interactive-simulations-in-html5/c/1Zm4l3sye20

It has an unfortunate break and is not visible in the welcome message. Chrome:

Safari:

I will try to shorten the welcome message to be completely visible.

[samreid]

I trimmed the welcome message and now it looks like this:

Leaving open to see if other developers know or can discover how to pin this to the top, and to address the topics in https://github.com/phetsims/tasks/issues/1018#issuecomment-653184407. Self-unassigning.

[zepumph]

I found https://support.google.com/a/thread/4876075?hl=en, which seems to make me think that this is possible, but I couldn't find that setting on the main client right now. Perhaps it was removed?

[samreid]

It seemed to me like it had been removed.