-
Notifications
You must be signed in to change notification settings - Fork 2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve high-level documentation about phetsims repos #1018
Comments
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 PhET's common-code README.md files are relatively sparse and stale. For example, here's the substance of
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. |
Improving READMEs of common repos sounds good in general. |
Note this overlaps somewhat with the automatic README generation in phetsims/utterance-queue#5 (comment) |
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. |
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. |
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.
Other topics for this issue:
|
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? |
I don't recall at all. @ariel-phet is the guy. |
Ah, now I remember. I'm going to create a "BREAKING CHANGES" thread in the Google Group. |
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:
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. |
@samreid could you start this thread on the google group (feel free to consult with @pixelzoom) |
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? |
Here is the old welcome message for our records:
If I add
It has an unfortunate break and is not visible in the welcome message. Chrome: I will try to shorten the welcome message to be completely visible. |
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 #1018 (comment). Self-unassigning. |
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? |
It seemed to me like it had been removed. |
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:
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.
The text was updated successfully, but these errors were encountered: