Provide and maintain stable versions of common libraries

[samreid]

For our open source community, and related to the POSE grant, one of the main pain points in improving our open source support (and potentially also for PhET developers and maintenance releases) will be making providing and maintaining stable versions of the code.

The main problem is that clients accessing PhET code on master are subject to breaking changes, which are documented in https://groups.google.com/g/developing-interactive-simulations-in-html5/c/1Zm4l3sye20. We have other discussions about change logs in phetsims/tasks#1084. When we make a change to our common code, we update all of the PhET-written sims, but clients would have broken code the next time they pull master (or they could be careful not to pull master and continue working from SHAs from an arbitrary timestamp).

The PhET Development Overview has a section called "Master is Unstable: Accessing rigorously tested code" https://github.com/phetsims/phet-info/blob/master/doc/phet-development-overview.md#master-is-unstable-accessing-rigorously-tested-code but that is not satisfying because it is centered on one sim, and doesn't have clear or semantic versioning.

This issue is for discussion, brainstorming and potentially prototyping.

It has been brainstormed that we would transition the common code repos into a monorepo #1242 (comment), but I do not believe that is necessary or desirable.

I believe master should remain unstable as we have been doing, which appears to be called "trunk based development" in the literature: https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development. Instead, we should provide tooling, and simplified instructions integrated into the "getting started" document about how developers can access semantically versioned branches in the common code, like so:

# clone perennial
git clone https://github.com/phetsims/perennial

# check out the latest stable version of the PhET Common Code
perennial/bin/clone-common-code.sh 1.2

This way clients can choose which version they want to work with and they will have control over when they upgrade e.g., from 1.2 => 1.3.

NOTE: In that script, I named it "PhET Common Code" because that is how our team refers to it, but I do not think that is the best name to make public.

To support this, PhET would

• create branches (or tags) for common code libraries. Could start at 1.0 for 1st release or 0.1 while we hammer things out.
• merge critical fixes from master into the last 1-2 supported branches.
• maintain change logs to help track breaking changes and assist clients upgrading branches
• create tooling to make it easy to create/operate on branches for multiple repos, compare versions, compare versions to master, etc.

I would like to note that even if we do the "bare minimum" for this issue: (a) creating "1.0" branches for common code repos and (b) adding a perennial script perennial/bin/clone-common-code.sh 1.0 and (c) documenting this in the PhET development overview, it would be minimal effort, would not disrupt our existing development process and would be a significant advantage over our current support.

Tagging other team members that have been involved in related conversations: @emily-phet @pixelzoom @zepumph @jonathanolson @BLFiedler @kathy-phet

[pixelzoom]

To make it feasible/scalable to create/test/maintain stable versions of common libraries, I think PhET needs to reduce the number of common libraries, by combining them into a smaller number of libraries (but NOT a mon repo). And I think that consolidation should be one of the first steps -- certainly before creating 1.0 branches of existing repos, as is proposed above.

[samreid]

Today @jonathanolson and @AgustinVallejo discussed with me and @zepumph about creating a new repo "phet-lib" which would be used to build a bundle which could be used for the scenery layout demos and other sandbox examples. I referred to this issue, since it overlaps a bit.

[samreid]

I think PhET needs to reduce the number of common libraries, by combining them into a smaller number of libraries (but NOT a mon repo). And I think that consolidation should be one of the first steps -- certainly before creating 1.0 branches of existing repos, as is proposed above.

In my opinion, merging some repos does not fundamentally change the nature of the problem. It does not give us atomic commits. It does not change the scripting/tooling we would need. Yes, we incrementally decrease the number of repos/commits/merges/changelogs/dependencies, but we lose modularity and modular GitHub issue tracking and have to pay an up-front merge cost.

I recommend that the next time we take RC shas (and hence blocks-publication issues are low), we use that as a checkpoint to branch common code repos as 1.0. Add a script that can check it out. We can decide later if we want to cherry-pick any fixes back into it. Document it and share it with the Google Group. Build it, and create single-file builds on the 1.0 branch of phet-lib. Bonus points: generate TSDoc. Nightly builds.