[FEATURE] Create infrastructure for examples

[marimeireles]

This is the umbrella issue to discuss ideas regarding how to deal with examples.

🏗 adding infrastructure:

• move examples to root of the repo (like docs) and point to them
• add a make examples cmd that basically copies the examples folder into where it is today and replaces https://pyscript.net/alpha/ with ./build/ so that we can test/run examples locally
• make sure that make tests run make examples if pyscriptjs/examples doesn't exist so that we can test examples locally
• somehow have a similar automation in CI so that we can test the examples before merging and make sure we are not adding regressions
• add linter for the code, it's a very similar infrastructure that we have here in the main repo, we just need to remove a bunch of things from the JS envs because we're not building pyscript itself
• decide which examples are going to stay in the core repo and which are going to be moved to collective, some more context

📖 add docs on how to:

• contribute new examples (basic infrastructure)
• how to add metadata for your project #21
• details on the examples approval workflow and acceptance criteria #20

📣 outreach work:

• get in touch with the extended community and ask if they want to have their examples included in the collective, see this comment for a list with some of the examples we have

[fpliger]

add a make examples cmd that basically copies the examples folder into where it is today and replaces https://pyscript.net/alpha/ with ./build/ so that we can test/run examples locally

In regards to that, I was thinking that this could be an additional cmd in Makefile. Something like that

cp -r ../examples ./examples
find ./examples -type f -name '*.html' -exec sed -i '' s+https://pyscript.net/alpha/+./build/+g {} +

[fpliger]

@pauleveritt This is sort of an umbrella issue for the effort that I mentioned to you earlier around starting a separate repo for community-contributed examples. If you are interested, I thnk it'd be a great opportunity to team up with @marimeireles to bootstrap this.

[pauleveritt]

I agree, this is a perfect sized task. @marimeireles what's the best place for me to help?

[marimeireles]

Hey @pauleveritt, thank you for offering help!
The first three steps of adding the infrastructure are basically done, so I'll take care of those.
Regarding the 4th I think we're still merging the infra and we should worry about it a little later.

I think the next steps here are to decided how to go about the examples and write some docs around it :)
Right now we have quite a few example PRs waiting for our resolution here.

• #278
• #158
• #113
• #141
• #40
• #39
• #398
• #151
• Add new example; Random Quote Generator. pyscript#512 (comment)
• chess example
• @fpliger slides :)

And IIRC even some examples in issues.

We have to:

• Decide which examples should live here in this repo and which ones should go to a repo dedicated to community examples. Some things to keep in mind:
  • the long term plan is to do a nice dashboard of examples in the pyscript website
  • the examples that live here are going to be directly used by our test suite, so I think things to consider is that they shouldn't rely on too many moving parts. For example the Mario + hand capture example doesn't seem like the best for us to run tests on, IMO.
  • because they're part of the test suite we should try to choose them in a way that they touch a broad part of PyScript's functionality
  • since this is the main repo I think it's the first contact of most people with PyScript so we should also think about offering an overview of PyScript functionalities
• Create an infrastructure to guide users on how to contribute new examples in this new repository
  • are we going to ask for some kind of documentation in conjunction with the examples?
  • we should point users to a best practices guide (I saw Fabio talking a bit about those, but not sure if we have anything in one place, if we don't we should probably create a document like this)
  • inform users which kind of examples we're looking for (or the approval workflow and acceptance criteria)

These are a few things I was thinking about. I'm very happy to hear your feedback and ideas @pauleveritt! I'm also available for a chat if you'd rather discuss something through video. You can send me an email and we can set something up.

Thank you again for offering help! Happy to work with you. :)

[fpliger]

🙌 🙌

[pauleveritt]

@marimeireles Chat sounds good. Is it ok if we switch to email? I'm paul dot everitt at jetbrains dot com.

[marimeireles]

Cool!
I'll get in touch =)

Another thing I'd like to add to the discussion after running the tests on the examples once is that it takes a very long time to run all of them. I wonder if we should take this into consideration on what kinds of examples we add here.
I read a comment by Roman (the pyodide maintainer) saying that the overhead on pyodide's running time is largely explained by how many packages we're adding and how big they are. It has to do with the translations pyodide is doing I guess? Not super sure cause I'm new to the WASM thing :) anyway, I'll bring it up to the people implementing the tests too.

[pauleveritt]

I have some experience with JS testing so it's something I could take a look at.

[pauleveritt]

@marimeireles Probably worth discussing out in the open, but what's the IP plan for this repo? Do you expect to have a contributor license agreement?

If so, then your plan makes even more sense. The examples in this repo are really for the needs of the project (documentation, testing) and less about showcase.

Moving community examples to another repo can then make that other repo a broader showcase. Not just examples, but articles etc. Kind of like an awesome-pyscript but nicer.

One place to ask beyond that. Years ago, I was involved with the Plone Collective. It was a place to take in new code which would have some common maintenance. You touch briefly on it. One could imagine helping people clean up their example on the way in, helping write a test for it, me perhaps making a video.

[fpliger]

That sounds about very in line with what we were thinking @pauleveritt . Examples in the main repo serve the purpose of documentation and testing (and part of the scope of work of core-devs) while examples/content in the community-examples repo (let's call it awesome-pyscript) be a community showcase that includes examples but can include more.

Both should have a contributor license agreement, imho.

[peterennis]

Linking pyscript/pyscript#495 here.
Seems like a consistent test/demo process would resolve these types of bugs.

[fpliger]

@marimeireles @pauleveritt just wanted to keep this alive and check if you made progress on a proposal of how to organize this or if you need help

[pauleveritt]

I sent @marimeireles a proposal. Should I send to you also @fpliger ?

[fpliger]

Happy to help :)

@marimeireles was out last week but she's back. I think it makes sense for you 2 to align and refine the proposal if needed and then publish it for discussion. I'm happy to chime in/review early on if you prefer or when you post the proposal, all good. :)

[marimeireles]

Hey Paul and Fabio.
So I'll just add some final things to the repo and open it to the public, so @peterennis can help polish stuff and add his ideas about how to contribute, etc. AFAIK we're all in agreement with the things Paul laid out on the document, because it's basically stating what we had discussed earlier in our meeting.

[fpliger]

Just as a pointer, was talking with @ramalho about documentation and, specifically, that there are some great 3rd party guides about PyScript out there. Would be great to also have a curated reference to these in this new repo as well

[marimeireles]

Yeah! @fpliger
That's the plan! :D

[marimeireles]

I think maybe we should have this issue as an umbrella issue that links to other issues?