search

phetsims / utterance-queue

Alerting library powered by aria-live
MIT License
0 stars 2 forks source link

Regenerate the README files. #5

Closed samreid closed 4 years ago

samreid commented 4 years ago

While I was working on https://github.com/phetsims/phet-info/issues/120 I tested regenerating a README file, and it showed me that the README files are now missing this line:

git clone https://github.com/phetsims/utterance-queue.git
zepumph commented 4 years ago

When I did the following commands, the utterance-queue line was added back in. 

cd gravity-and-orbits
grunt published-readme

@samreid how would you recommend gathering a list of published repos to call grunt published-README on?

samreid commented 4 years ago

How about changing grunt update so that it automatically updates the README, based on looking at the versions in package.json?

zepumph commented 4 years ago

This should be done soon. I should have already gotten to it as all published readmes are broken. Elevating priority.

zepumph commented 4 years ago

@samreid please review https://github.com/phetsims/chipper/commit/3bd063a5bb6851fe873c4f8234ef9350e0e1e838. Note that it worked to ignore sun, as well as working expected for natural selection (unpublished) and GFL (published).

Here are the current sims that don't yet work:

These are edge cases that the SimVersion logic added to grunt update doesn't yet handle

Please review that commit, and spot check the rest. I used perennial/data/active-sims as the list to grunt update. @samreid how to you recommend to proceed? I feel like we may want better logic about what a "published" sim readme is.

samreid commented 4 years ago

@zepumph this looks great, thanks! I made a few improvements in the commits. For dealing with the outliers in https://github.com/phetsims/utterance-queue/issues/5#issuecomment-574906235, I recommend adding a new package.json entry like "readmeTemplate:'...'" which is the relative path to the readme template to use. That way some repos can always use the "unpublished" template, and other sims can define their own template, which will be filled in with the template variables. Does that sound OK to you?

zepumph commented 4 years ago

That way some repos can always use the "unpublished" template, and other sims can define their own template, which will be filled in with the template variables. Does that sound OK to you?

I think this is halfway there. To me, when specifying something manually, you are opting out of both published and unpublished readmes, so I think instead there should be a package.json entry that tells grunt update to not try to auto generate the README.md file, since it is manual. I got to this solution via yours because in the outlier repos, it will involve having a template readme that is the exact same as the readme itself. I'll try a first pass and see what you think.

zepumph commented 4 years ago

The above solution is working really well so far, and will cover permanent cases like blast, but doesn't cover the case where a brand new sim is in RC but not published. Is it alright to just say that it is ok to have a published readme for that case (upwards of a month or two of inconsistency once per new sim)?

zepumph commented 4 years ago

Summary of work:

One cleanup question I had was questioning if we have a central place where the schema for a sim (or general) package.json is defined. Should we make this? Otherwise there is no place to document readmeCreatedManually but to look at the usage. What do you think? @samreid please review.

samreid commented 4 years ago

A note for when I review this: in https://github.com/phetsims/tasks/issues/1018 we discussed improving the readme files. I wonder if we will want them to be templates so we can fill in the git clone dependencies?

samreid commented 4 years ago

Looks great, thanks! I moved https://github.com/phetsims/chipper/issues/913 to a new issue. If we decide to make READMEs' based on templates, that can be done in https://github.com/phetsims/tasks/issues/1018, closing.