Dev onboarding document needed

[zepumph]

There seem to be a lot of spots that new-dev documentation exists. I'd like a central place. The Development Overview is definitely a great start, but it doesn't include stuff that PhET employees might need to do that open source users wouldn't.

[zepumph]

Document available now at https://github.com/phetsims/phet-info/blob/master/doc/new-dev-onboarding.md

[zepumph]

Updates above from recommendations that @pixelzoom had on slack. From here I will assign @AgustinVallejo and @marlitas. Please read through and make any updates that may be helpful. You don't have to add anything if nothing strikes you. When done please unassign yourself. If you are the last one feel free to close this issue.

[marlitas]

This is less about the content of the doc and more about organization/presentation. As a new dev it can be very overwhelming walking into the PhET codebase as well as the code standards. I know for myself I would open some of the docs during my first week and feel like I couldn't handle that amount of information with the other onboarding that was happening (CU benefits/employee setup, meeting everyone, introduction to sim design, etc.). Wondering if there could be a recommended timeline, or perhaps presenting the info/required steps in an order that would be most beneficial (ie. do this first, then this). OR, we provide more buffer time in the first week to look through all the docs before digging into any aspect of the codebase.

[zepumph]

• [ ] Add a section about "helpful tools" for things like snapshot comparison, phetmarks, and aqua fuzzing.

[zepumph]

• [ ] @AgustinVallejo also mentioned adding the scenery doc and examples for this do too.

[zepumph]

Today at dev meeting we discussed this issue. In response to https://github.com/phetsims/phet-info/issues/192#issuecomment-1124021948, that context seems really important. Another way of formatting that would be with an explanation of each document saying "this is reference, don't memorize this your first day" vs the more step-by-step setup guides. A subgroup of @jbphet, @marlitas, @AgustinVallejo, and @chrisklus will take this on.

[marlitas]

2/25/22 Onboarding Documentation Club Meeting @jbphet @chrisklus @AgustinVallejo @Luisav1

Base Foundation:

• Adding useful demos (sun, tambo, joist, scenery-phet, twixt)
• Repos with documentation on phetmarks (dot, kite, scenery)
• Introduction to phetmarks
• Add section: "You'll be assigned a mentor and your mentor can provide a more specific reading list."
• Highlight which sections of development-overview are most useful.
• Create sections based on when documents may be useful in the onboarding journey.

Brainstorming:

• MS: To-do section: administrative tasks that you should check on/get done during onboarding.
• CK: Want to make sure we are not duplicating documentation, linking to stuff that already exists.
• AV: Adding guide on common code usages? p5js.org/get-started is an appropriate example
• JB: Create guided exercises. Starts to provide developer with an idea of what is where and how to navigate repo.
• MS: Github markdown flowchart integration: mermaid

[marlitas]

@jbphet : Flesh out intro @chrisklus & @Luisav1 : Finding other documentation and linking it back @marlitas : research mermaid @AgustinVallejo : Top topics for tutorials or exploration (guided exercises?)

[AgustinVallejo]

01-06-2022:

• We should link all the learning resources for new devs: Coursera, OReilly, LinkedIn Learning. To learn Typescript and JS.
• Reccomended resources from team members.
• Link to MDN Glossary for JS words
• Are we writing for PhET Developers or for anyone who wants to write PhET Sims?

Tasks: @jbphet : Ranking the Design Pattern sections. @AgustinVallejo : Linking Design Pattern sections to the development process. @marlitas : Making a mermaid map for the possible development process. @chrisklus and @Luisav1 : Keep going on the first steps documentation. Addd phetmarks

[marlitas]

• Add phet globals to onboarding doc.

[pixelzoom]

You might also want to add something about query parameters:

• chipper initialize-globals.js for general global query parameters (preloaded)
• phet-io phet-io-initialize-globals.js for PhET-iO global query parameters (preloaded)
• {{REPO}}QueryParameters.js or {{REPO}}QueryParameters.ts for sim-specific query parameters
• Query parameters are by default "for internal use only" and should not be shared outside of PhET. Public-facing query parameters must be explicitly designated by including public: true in their schema.

[marlitas]

Meeting 6/8/22

Read over Background reading section:

• Tutorial/Exercise for devs to try after reading MVC & MVT sections
• Tutorial/Exercise after Observer section
  • Written at high level and reference existing sims that are maintained.

PhET Dev Overview => How to link

• Reference small sections as necessary
• Create table of docs glossary at bottom, for easy onboarding navigation.

Flowchart

• Add github account to Environment Setup
• Change "Code Snippets" => "Background Reading"
• Arrow from"Code Snippets" going through "Simula Rasa", way to fix? Or are we stuck?
• Change "Environment Setup" => "Initial Setup"
• Remove "Simula Rasa"
• example-sim ---> Building, Modifying ("Play" you can break things don't commit)
• Place "Node Tree" before "Flexbox/Gridbox"
• Fix IDE Document link.

First Steps:

• Change name to "Initial Setup" to match flowchart.

Navigating Repos Section:

• These files serve their purpose but you won't interact with them much.
• Typical directory structure ex. (Link to CRC)
• Link to example TS repo that has good example of typical structure.

Query Params:

• Add section to document commonly used queryParams
• Suggest by @pixelzoom:
  • chipper initialize-globals.js for general global query parameters (preloaded)
  • phet-io phet-io-initialize-globals.js for PhET-iO global query parameters (preloaded)
  • {{REPO}}QueryParameters.js or {{REPO}}QueryParameters.ts for sim-specific query parameters.
  • Query parameters are by default "for internal use only" and should not be shared outside of PhET. Public-facing query parameters must be explicitly designated by including public: true in their schema.

@marlitas suggested perhaps prettifying the document a bit? Others were not opposed.

@AgustinVallejo - Will research and start writing tutorials/exercises @jbphet - ^^ Will help with research and brainstorming @chrisklus @Luisav1 - Will add QueryParams sections and edit First Steps @marlitas - Flowchart changes & create docs glossary table

[zepumph]

Hey all! It looks like some really great work is happening here, thanks! I had an idea to include some info about slack. Basically making sure you subscribe to developer, dev-public, and continuous-testing, and to make sure that you are set up to be notified about all messages on continuous-testing. I hope that helps.

[pixelzoom]

Mentioned in today's status meeting. In https://github.com/phetsims/phet-info/commit/07b0a69165346a63a4e94073e92ab0482defad8b, @jbphet added a ranking of design patterns. It would be nice to put that info in the actual design patterns doc, so that it's available to readers of that doc, and so that it doesn't become stale by being in this doc.

[AgustinVallejo]

Meeting june 15, 2022

• Make an individual issue and fork (TBD) for every tutorial solution.
• Mention to discuss with mentors other possible slack channels
• Add slack tutorials: Here
• Design Patterns should be the first item in Reference Documents
• For the Roadmap:
  • Link to tutorials
  • Link to Design patterns
  • Link to Typescript Conventions
  • Link to Scenery Layout docs
• Glossary:
  • Merge it with the Reference Documents section
  • Review the phet-info/doc documents to add the relevant ones and prune the obsolete ones.
• Advice for new devs to make an issue on obsolete content in the onboarding docs.
• Remember the Navigating Repos section!!

Tasks: @marlitas : Link to flowchart elements and experiment with forks for tutorials. @chrisklus and @Luisav1 : Include the rest of the mentioned changes (Slack, query params, etc.) @jbphet : Merging the glossary with the Reference Documents and also add phet-info documents. @AgustinVallejo : Create the tutorial files. Also Navigating Repos section.

[marlitas]

Forking experimentation:

• Successfully forked and cloned example-sim and got it up and running.

Recommendations / Instructions:

• fork example-sim (place fork under your personal github ownership)
• git clone in phetsims root directory changing the directory name to {{GITHUB}}-example-sim (ex. git clone https://github.com/marlitas/example-sim.git marlitas-example-sim)
• Launch server ( from phetsims root directory) and transpile as normal
• Visit http://localhost/{{REPO_NAME}}/example-sim_en.html to access forked example-sim.
• Make sure that any changes and commits for the purpose of the tutorial are being made inside the {{GITHUB}}-example-sim directory.

EDIT: To transpile the repo needs to be added to active-repo-list... may need more work/discussion for this to be fully effective.

[AgustinVallejo]

Added the challenges doc! https://github.com/phetsims/phet-info/blob/master/doc/phet-dev-excercises.md

[jbphet]

Meeting June 22, 2022

• @marlitas has been trying the fork approach, and has made progress, but there is a ways to go. She and @chrisklus will pair to see if they can make it work.
• @Luisav1 and @chrisklus added links for Slack tutorials, query parameters, and info about how to clone PhET repos
• @AgustinVallejo started on tutorials and showed progress thus far

Next Steps:

• @AgustinVallejo will investigate some of the formatting issues that we were seeing with checkboxes in the docs this week
• @marlitas will work on some restructuring of the first sections such that the headings are more specific, making it clearer what each sections contains, instead of "First Steps" and "Next Steps"
• @jbphet will work on merging the glossary with the Reference Documents and also add phet-info documents
• @Luisav1 will start on the Navigating Repos section, which is a general overview of how repos are structured

[marlitas]

@zepumph taught me some things about ways I can run unit and fuzz tests locally when making common code changes. He mentioned that @AgustinVallejo also did not know about aqua, or QUnit, and we both wondered if it might be a good idea to include a section on testing for new devs that may be interested/ have use for it when they start to work in common code. Up until now it's been a lot of committing and praying on my part, which seems less than helpful.

Commenting for discussion at next Meeting.

[marlitas]

Meeting 6/15/22

Formatting:

• @AgustinVallejo did not find any useful info about the weird checkbox formatting. We changed to bullets.

Layout:

• @marlitas change "Sim Environment Setup" to "Dev Environment Setup", Add link to tutorial in mermaid chart to "Modify and Experiment"

Navigating Repos:

• Add subsection to "Ramping Up". Will advise devs to checkout CRC Repository Structure for more info.
• Include blurb about asking mentor for initial structure explanation.

Testing:

• Adding section about Aqua and QUnit
• Link to CT

TODO:

• @chrisklus will add Testing section
• @marlitas apply layout changes
• @Luisav1 apply navigating repos
• @jbphet Merge glossary with Reference Documents and add phet-info documents
• @AgustinVallejo continue working on tutorials

[jessegreenberg]

• [x] There are steps to add about auto imports for built-in types in WebStorm, see https://github.com/phetsims/chipper/issues/1270

[marlitas]

@chrisklus and I were able to get my forked copy of example-sim working on my local machine.

Instructions for Forking:

• fork example-sim (place fork under your personal github ownership)
• git clone in phetsims root directory changing the directory name to {{GITHUB}}-example-sim (ex. git clone https://github.com/marlitas/example-sim.git marlitas-example-sim)
• add {{GITHUB}}-example-sim to perennial/alias active-repos
• Edit line in example-sim_en.html, to load modules from '../chipper/dist/js/{{GITHUB}}-example-sim/js/example-sim-main.js'
• Launch server ( from phetsims root directory) and transpile as normal
• Visit http://localhost/{{REPO_NAME}}/example-sim_en.html to access forked example-sim.
• Make sure that any changes and commits for the purpose of the tutorial are being made inside the {{GITHUB}}-example-sim directory.

A couple of concerns and questions came up from this:

• Editing the name of the repo only on one line in example-sim_en.html seems wonky. There are still many other existing references to the original example-sim.
  • Does this make forking too difficult/clunky?
  • Users would have to stash their changes to perennial-alias active-repos before pushing. Making the barrier to entry, and usability much more difficult/complex.
• @chrisklus suggested branching off of the original example-sim as another option.
  • Concerns then came up about answers to the interview-test being easily accessible to future candidates.
  • Is this something that can be avoided through the content of the tutorial?
  • Is this actually okay and not a concern?
  • Other than interview-testing being affected, branching seems to be the smoothest implementation we talked through.
• Another suggestion was to fork, and create a parallel phet repo for the forked sim.
  • If people want to clone other's tutorials to look through them this could create many unnecessary copies of common code repos on one machine.

We would like to discuss this with the onboarding team before making a recommendation.

[chrisklus]

From 7/6/22 meeting:

@jbphet is going to reach out to @matthew-blackman to make sure he's aware of the onboarding doc we've been working on. We would also appreciate any feedback from MB about this doc as he's working through it, and will invite him to a meeting to share.

@marlitas and @chrisklus talked about our findings from https://github.com/phetsims/phet-info/issues/192#issuecomment-1172663328 and we decided that using branches for working through tutorials in example-sim seems like the best way to go. We will present this idea to the dev team to make sure everyone is on board with that.

We updated the setup doc for WebStorm to include some new suggestions, like what was mentioned in https://github.com/phetsims/phet-info/issues/192#issuecomment-1171531194

Next steps:

@jbphet Merge glossary with Reference Documents and add phet-info documents @AgustinVallejo work on tutorials @marlitas apply layout changes

Adding this issue to dev meeting to discuss using branching for working through tutorials in example-sim.

[marlitas]

On Slack @pixelzoom said:

For those devs working on the onboarding doc, this might be something to point to (if you haven’t included it already):
https://github.com/phetsims/special-ops/blob/master/doc/phetTeamMember.md

For discussion at next meeting.

[pixelzoom]

Also regarding https://github.com/phetsims/special-ops/blob/master/doc/phetTeamMember.md ... That document contains private information, which is why it's in the special-ops repo. Be careful not to expose any of that information in public documents.

[marlitas]

7/13/22 Meeting:

@jbphet and @AgustinVallejo out on vacation.

@chrisklus, @Luisav1, and I added phetTeamMember.md link to the documents section.

Will connect once the rest of the subgroup is back. Everyone enjoy vacation!

[AgustinVallejo]

https://github.com/phetsims/chipper/issues/1281#issuecomment-1191882112 We need to discuss as to where to add the TS standards information in the Onboarding process.

[pixelzoom]

Re (4) in https://github.com/phetsims/chipper/issues/1281#issuecomment-1185933099 ... I want to clarify that's there's nothing in that item that's specific to TypeScript, and it's not a convention. It's best practices for API design for any typed/OO language. So while it technically doesn't belong in a TypeScript Conventions document, I'll leave that decision up to the onboarding subgroup.

[kathy-phet]

We talked about putting (4) in some other part of the Onboarding documentation, but in general, discussed that it would be good to have this information somewhere for devs coming to the team that are newer to Object Oriented code conventions - e.g. coming from a pure javascript background where OO is not the norm (as I understand it).

[marlitas]

With all the updating of pre-commit hooks and absolute-tsc I decided it was finally time to add the tsc alias to my .zshrc file. I looked in the onboarding doc for instructions and it says: Check lint and tsc separately by running grunt lint or tsc in a sim repo.

This does not work. I receive a command not found error. We need more instructions as this bullet makes it seem like tsc should be built in already.

[marlitas]

I also wanted to add a comment to revisit adding a section or bullet point about ways we are able to test code. Language about CT, Aqua, and QUnit would be helpful as guiding points for new developers. Many of these I didn't even know existed until someone happened to tell me, and it's very difficult to ask questions about things you don't know are there.

[marlitas]

8/3 Meeting

Updates:

• @jbphet consolidated both documents sections into "Resource Documents". Would like to move this section to the end, and we agree
• @AgustinVallejo is working on tutorials, will start them up again this week.
• @marlitas brought up adding a testing subsection, @jbphet said he can put this on his radar to add info about CT and fuzz testing, @marlitas will do more research about QUnit/Aqua and add necessary info.

Discussions:

• We'll reach out to MB once tutorials are done.
• We are going to bring up the idea of creating branches on example-sim for exercises at dev meeting.
  • We discussed opening an issue alongside the exercises
  • We decided that opening an issue and assigning it to your mentor once exercises are complete would be the best option in terms of keeping track of exercises as well as introducing new devs to our issue workflow.
  • We are asking dev team about their tsc habits at dev meeting.

Action Items:

• @jbphet: continue adding docs to "resource documents", and move section to end.
  • Will add subsection about CT
• @marlitas: add info about Aqua and QUnit
• @AgustinVallejo: finish up tutorials
• @Luisav1: is available to help as needed!
• Next week we will talk about item 4 in: https://github.com/phetsims/chipper/issues/1281#issuecomment-1185933099
  • Please read ahead of time.

[marlitas]

Meeting 8/10/22

Action Items:

• @jbphet will add bullet point about typescript standards referencing: https://github.com/phetsims/chipper/issues/1281#issuecomment-1191882112
• @AgustinVallejo will finish up tutorials
• @Luisav1 will do a grammar/editing read through
• @marlitas will reach out to MB about coming to our 8/31/22 meeting

[marlitas]

Quick update for the team: I have learned how to get emoji's to render in intelli-j! 🥳

It's much easier than I thought. Instead of using github's colon-emoji syntax you want to use your keyboard's emoji short cut ctr + cmd + space (mac), windows-logo + . (windows). This will open an emoji dialogue box for you to choose from. Intelli-j knows how to render this out of the box. I will update all usages of colon-emoji syntax to this.

I also discovered how we can get mermaid flowcharts to render in intelli-j as well. I will do a PSA on this for devs at Thursday's meeting in case there's ever a point we want to use mermaid charts more in our documentation.

[jbphet]

Notes from review discussion with @matthew-blackman:

• In general he found it very valuable and saved a lot of time
• It would be helpful to have a bit more "best practices" information, such as
  • Running a pull-all first thing in the morning
  • How much we use github issues for communication
  • How to target commits for specific issues and features, i.e. the scope of commits
  • How and when to use assertions
  • Using the debugger keyword and looking at the sim state
  • Using the profiler in Chrome
  • Using the PhET profiler
  • Using memory profiling
  • Using External Tools from the IDE
  • running pre-commit hooks
  • running TS transpile all with usable links
  • shelving
  • Stashing
  • Show history (for selection and for the whole file) in the IDE
  • Setting up a local server
  • Using live templates
  • GitHub co-pilot
• We should add links to the developer notes
• We should add links to the developer project board and some notes about how we use it
• It would be helpful to have more explanatory information about what each of the common-code repos are for, and it would probably be best to have that in the readme files

Our next step will be to prioritize and assign people to follow up on these items. It was pointed out during the meeting that we want to do this without making the document too much larger, since one of the goals is to keep it fairly compact and therefore not overly intimidating to new devs.

[jbphet]

@AgustinVallejo and I were the only team members that were able to make it to the 9/7/2022 meeting. We reviewed the list in the previous comment, which was the feedback from @matthew-blackman's usage of the document while ramping up. Our recommendation is to take this list and put it in a section entitled something like "Tips, Tricks, and Best Practices" that would go between the current "Sample Roadmaps" and "Reference Documents" sections. It would start off with an introductory paragraph that essentially says, "These are some things that you'll want to learn about eventually, ask your mentor about each when the appropriate time comes" and then have a bullet list with each of these items including a very short explanation.

[jbphet]

During the 9/14/2022 meeting of the onboarding process task force, we came up with the following next steps:

• Divide the "Ramping Up" section into "Introductory Development" (@marlitas) and "Advanced Development" (@chrisklus & @Luisav1).
  • Debugging should be in the introductory section
  • Pull all first thing in the morn should be introductory
  • Memory profiling should be in advanced
  • Using external tools could go into the IDE setup guide
  • Setting up a server is already covered in the
  • We should add some information about patching to the advanced section
  • Show history should be in the advanced section
• Add section called "Project Management" that has a brief explanation of how things are managed, but not so much detail that it will soon become obsolete. This will include links to the quarterly planning page and the developer project board. It should also talk about how much we use GitHub for communications and record keeping. (@jbphet)

[chrisklus]

From 9/15 subgroups discussion, we think we should mention that most devs use Chrome development (and test in other browsers too), so we should a simple section that just links to https://developer.chrome.com/docs/devtools/. This should be added to the introductory development section.

[jbphet]

I spoke with @ariel-phet over Slack, and he said he'd be up for taking an editorial pass through the primary onboarding document. I think it's ready for this, and I think the group has spent about as much time on this as we reasonably can. @ariel-phet - Feel free to make edits that you think will improve the readability and flow, and you can add any big suggestions in this GitHub issue. There are a number of other documents that are linked from the main one - don't feel any need to review those. We mainly want something that is a reasonably good starting point for new developers.

The doc can be found at https://github.com/phetsims/phet-info/blob/master/doc/new-dev-onboarding.md.

[ariel-phet]

@jbphet @chrisklus @AgustinVallejo @marlitas I have read over the document and made some corrections/edits, but overall the information looks really great.

Three suggestions I would have are:

• [x] Add a small section that describes "common code" -- common code is mentioned several times in the document but it would probably be good to define and give some examples of common code libraries. I feel like although we are comfortable with what common code refers to, that might be a bit confusing, especially when there are also sim specific "common" repos -- it would be good to disambiguate this various ideas and give a few examples

• [x] Explain what we mean by a "dev version" under the Publishing a Sim and the reasons you might publish a dev version. Again, I feel like our internal definition of "dev version" might not be obvious to the new user or the reasons why we publish one.

• [x] Should there be any short mention about the QA team its role at PhET since devs and QA work together quite a bit?

[samreid]

@jbphet said he and @AgustinVallejo can wrap this up. Perhaps @marlitas would help. It no longer needs to be on the planning board, and can be treated like an emergent/choice issue.

[jbphet]

@AgustinVallejo and I just spent some time folding in @ariel-phet's feedback, and I think we've done as much as time permits. @marlitas - if you would like to have one last look through it, you're welcome to do so, otherwise I think we can close this (huge and epic) issue.

[marlitas]

I reviewed, and update some wording around the new management processes. It looks really good and seems like all the work here is done. Closing!