What can we do to prepare papyrus for open source contributions?

[brettfiedler]

@emily-phet and I discussed the opportunity here to make the repo friendly to open-source contributors. This is based on an open-source project and based on our other discussions about PhET in general, this seems like a manageable piece to put into practice our goals of creating a welcoming open-source community. If we can do this and point to features we'd like to see developed but are unable to commit resources to, then that is a bonus to the whole endeavor.

Using opensource.guide as a... guide. I've started building a list of items we should accomplish to transition the repo:

TODO to make this repo open-source friendly

GitHub-specific:

• Make repo welcoming
  • [x] Consider renaming the repo to be more unique and clear about purpose (papyrus is a programming language... oops)
  • [x] README.md (e.g., these resources)
  • [x] CODE_OF_CONDUCT.md
  • [x] CONTRIBUTING.md, GitHub automatically provides anyone making an issue with this file. (e.g., Mozilla How-To))
  • [x] Update LICENSE.md
  • [x] Make use of Issue tag (good first issue) (GitHub automatically prioritizes these issues for visitors to the repo)
  • [x] Pull request and Issue Templates
  • [x] Open up Github discussions!
  • [ ] Clean up Project board for public viewing or consider alternative way to indicate project organization and priority

Codebase: (these require issues of their own for devs to progress)

• What can we clean up in the repo that we don't need?
• Commenting as though someone not in PhET is definitely going to edit this
• Maintaining ability to run the tool without reliance on PhET resources (that aren't already packaged with the tool) or hosted services. This includes being able to run a local database if desired.
• Synchronize program database with repo. Or at least the "approved templates" we intend to create.

Non-GitHub Community/Documentation

• Advertisement & solicitation (collaborators, web communities, etc)
  • https://opensource.guide/building-community/
• CU webpage as option for friendly introduction and then links to documents for devs (APIs, etc)
  • Consider rewording of Contributing and ways to contribute
  • Consider FAQ
  • Consider resources to do dev/web dev

[brettfiedler]

I'm currently working on the .md files on my local machine. When those are complete, I'll push them to the repo, and they can be edited and changes committed directly through GitHub.

[brettfiedler]

@emily-phet, made a few passes at editing the top post. Feel free to directly edit it with additions/modifications.

[brettfiedler]

I don't think this is a requisite for the repo documentation, but for a user-facing website, it might be nice (read: optional) to include a section similar to this (https://foundryvtt.com/article/intro-development/) that points users towards web dev resources or at least JavaScript resources that would help them in developing Programs.

(side note: it'd be nice from the POSE perspective to have scenery documentation point toward learning resources for all of its languages/frameworks)

[brettfiedler]

Just a few names to toss into the ether:

• CoDevise (also has code in the name) + suffix (PG, Playground, JS)
• Interaction Playground
• PaperPlayground (doesn't really hint to the goal of the tool)
• CoPaper
• Collabopaper
• paperNplay
• CoDesignPlayground
• ScriptCollab
• CollaboSense + suffix
• CollaborAction + something
• Playper (from JB)

[brettfiedler]

Dropping this information unceremoniously here as helpful for the README and CONTRIBUTING docs:

Will need to be clear about what functionality we’re adding that align with the MVC framework, that in order to use our packaged libraries, you’ll need to abide that framework, and that the examples have strict adherence. However, the tool can be used without any of that if you choose.

[brettfiedler]

I've decided to go with statically hosted documentation via GitHub Pages for now to provide all the information folks need to setup, use, and participate with paper-land.

Currently using Mkdocs to build the site and run a scripted deploy to the gh-pages branch in this repo. Need to get GitHub Actions set up to autodeploy on push/pull request next.

Steps (added to docs-deploy.txt in docs directory):

Our documentation uses Mkdocs and is statically deployed with a pre-configure plugin for Mkdocs to GitHub Pages. The built website is created on the gh-pages branch

mkdocs.yml is a required file and sets up the navigation tree for the website.

.readthedocs.yaml is not required to deploy using the steps below. However, it does provide an alternative way for continuous deployment configured and freely hosted by Read The Docs. For now, we have not gone this route, but it's set up to do so. The plan is to use GitHub Actions once it's configured to deploy automatically every push/pull request.

To deploy to the documentation website from a local machine (same steps GitHub Actions needs to do):

• Install Python (3.11 last supported at deploy)
• Install module requirements using pip install. Install using the requirements.txt file in this directory.
• run mkdocs serve to locally host the directory and preview changes in real time.
• When ready, run mkdocs gh-deploy and it will automatically build and push to the gh-pages branch and kick off GitHub Pages to run a deploy Action.

[brettfiedler]

This is complete in its first iteration!