[devOps] Move examples from ml5-example into the core ml5-library repo

[bomanimc]

Dear ml5 community,

I'm submitting a new issue. Please see the details below.

→ Step 1: Describe the issue 📝

Did you find a bug? Want to suggest an idea for feature?

Suggesting an idea. Please let me know your thoughts! Feel free to tag anyone that you'd like to make sure sees this.

→ Step 2: Screenshots or Relevant Documentation 🖼

Here's some helpful screenshots and/or documentation of the new feature

Context:
I'm in the process of thinking about ways to simplify the devops process for the ml5 library, working with @joeyklee! Part of the process of getting to a simpler devops process is simplifying the development workflow overall. I think that consolidating these two repos may be a step towards a simpler development workflow.

There are few challenges with the current separation of repos:

• Difficulty coordinating the release of features and examples: Currently, the release of examples and features must be coordinated manually. For example, if I add a new GAN model to the core library, I'd need to have it launch in a new release of the core library and then subsequently update the examples repo. While developing a new feature for the ml5-library, it's typical to create a simple example to test out the functionality and ensure that it works anyway, so it'd likely be helpful to have a monorepo where examples and core functionality can be developed, tested, and released at the same time.
• Unclear Separation of Issues: Many of the issues that are submitted to the ml5-examples repo are related to bugs with core functionality in the library OR are asking for help on specific projects. Additionally, issues that are actually detailing problems with the examples are often fixed by improvements to the core library. Overall, this makes issue management a bit more challenging becuase problems/questions are duplicated. From a library user perspective, there's two sources of truth for information and support.

Proposed Approach:

• Create a new folder in the ml5-library repo called examples/. Inside of it, place the examples for each of the models inside, accounting for the pure JS and p5 versions of the examples (i.e. ml5-library/examples/p5js/FeatureExtractor/FeatureExtractor_Image_Classification/).
  • Alternatively, example code could live in ml5-library/src/UNET/examples/p5js/ and we could update the build system to collate only these directories into an examples distribution folder.
• Create a new Netlify project to serve the examples online (e.g. examples.ml5js.org) and trigger builds when new changes are pushed to the release branch. If a build process is required for the examples, specify a build script for the examples in Netlify and tell Netlify to serve the resulting dist_examples/ folder.
• Optional/Extension: Setup the example HTML templates such that they point to the local dist/ folder to reference the local development copy of the ml5-library to make it easier to do manual testing with the examples. See thread here for ideas.

I'll be submitting a few PRs to switch our examples away from referencing a specific version of the ml5 library via UNPKG, but if we want to continue to support specific version numbers in imports we could:

• Edit index.html files to use a template parameter when specifying the ml5 version in the src tag. See HTML-Webpack-Plugin documentation here.
• Update the build process to create a new dist_examples/ folder which contains the processed examples code. Edit the build process to use the version of the core ml5-library specified in the package.json file (e.g. 0.4.3) to replace the HTML template parameters in the template HTML files.

Pros:

• Consolidating the ml5-library repo and the ml5-examples repo means that we remove an additional repo to handle in the devops workflow. Rather than needing to make updates to version numbers across two repos, we can focus on only a single large repo.
• Putting the examples in the core ml5-library repo potentially makes it easier to update examples as library features changes, while also keeping the release of these changes in sync. For example, if a function name gets deprecated in the core library, the example can be updated and merged into the development branch. Updates to the public examples website will only occur when the changes are merged into the release branch.
• If we want, this approach still allows us to maintain an explicitly specified version number within imports of the ml5 library used in examples.
• Remove GitHub Pages deployment from the overall DevOps workflow and centers everything around Netlify resources.
• Optional Extension: Putting examples in the core ml5-library repo could be used to improve the manual testing workflow. Build systems can be set up to allow people who are working on changes to the core library code to easily open the examples to verify that the changes haven’t caused any noticeable regressions in user-perceptible functionality.

Cons:

• There’s community, discussions, and history built up around the ml5-examples repo that may be lost/disrupted if we archive this repository
• Maintaining examples in the core library repo may add some bloat to the ml5-library development codebase and could also add more noise to the issues (i.e. more issues on the ml5-library repo about specific examples)
• People looking at the repo for the first time and hoping to copy the example HTML file from the GitHub may struggle with the Webpack template parameters in the example HTML file because they don’t know to replace it with a specific ml5 version.
  • @joeyklee explains that most people are looking at this code through the web editor, so this will probably not be a major issue.

[bomanimc]

cc: @joeyklee and @shiffman. Please tag anyone else who may have feedback to add to this!

[joeyklee]

Tagging @yining1023 who might also have some thoughts since she has also worked extensively on the library!

[joeyklee]

Hi @bomanimc!
Thanks so much for this wonderfully structured issue and coherent and thoughtful ideas.

My two cents:

Re: Cons

There’s community, discussions, and history built up around the ml5-examples repo that may be lost/disrupted if we archive this repository

• My feeling is that since many of the issues currently point to issues related more to the library than the example specifically, I think it makes most sense going forward to bring the repos together.

Maintaining examples in the core library repo may add some bloat to the ml5-library development codebase and could also add more noise to the issues (i.e. more issues on the ml5-library repo about specific examples)

• I'm less worried about the issues creating noise since, however it will definitely bloat the library since we also have some data and models that live within the ml5-examples repo.

People looking at the repo for the first time and hoping to copy the example HTML file from the GitHub may struggle with the Webpack template parameters in the example HTML file because they don’t know to replace it with a specific ml5 version. @joeyklee explains that most people are looking at this code through the web editor, so this will probably not be a major issue.

• Hmmm, one thing to keep in mind is that the index.html files are not all the same in the ml5-examples. Some examples have DOM elements written directly into the HTML file which either necessitates the existence of all the examples as individual folders OR the rule we enforce is that no more DOM elements in the HTML.

Re: Pros

Consolidating the ml5-library repo and the ml5-examples repo means that we remove an additional repo to handle in the devops workflow. Rather than needing to make updates to version numbers across two repos, we can focus on only a single large repo.

• yes! 100%

Putting the examples in the core ml5-library repo potentially makes it easier to update examples as library features changes, while also keeping the release of these changes in sync. For example, if a function name gets deprecated in the core library, the example can be updated and merged into the development branch. Updates to the public examples website will only occur when the changes are merged into the release branch.

• Yes! Also since this is usually the workflow for integrating new changes into the library, it could potentially make it more seamless and encouraging for people to submit their examples with their feature submissions or bug fixes.

If we want, this approach still allows us to maintain an explicitly specified version number within imports of the ml5 library used in examples.

• Totally.

Remove GitHub Pages deployment from the overall DevOps workflow and centers everything around Netlify resources.

• I am happy to support this. Netlify-ing our resources could make it easier to have a better overview of all the things on the web and remove the need for gh-page branching craziness!

Optional Extension: Putting examples in the core ml5-library repo could be used to improve the manual testing workflow. Build systems can be set up to allow people who are working on changes to the core library code to easily open the examples to verify that the changes haven’t caused any noticeable regressions in user-perceptible functionality.

• Ah yes! Right to the point!

[bomanimc]

I would love to get more feedback cc @shiffman @yining1023, but in the meantime, I'll put together a PR for this change so that folks can get a sense of the change!

What I'm also interested in exploring is if the examples could be a submodule inside of this repo and later imported into the ml5-website repo so that all of the frontend styling/templating for the examples page https://ml5js.github.io/ml5-examples/public/ and the hosting can be handled in that repo (rather than having those pages and the deployment process live here. I'm not sure yet if this is actually an optimal approach, so I'll consider in a separate issue after we make a decision on this one.

[shiffman]

Hey @bomanimc and all, thank you so much for this comprehensive and thoughtful discussion! I think your plan of consolidation sounds like a good one and I am in full support! Before we had the examples all running in the web editor, the ml5-examples repo was the primary way for beginners and students to find and run the examples. But now that we have the web editor, I think we can optimize for the build process and consolidate the examples into ml5-library.

My knowledge and experience with git submodules may be out of date, but the last time I used them with a project (at least 2-3 years ago), it created a lot of roadblocks for contributions as the commands to run to properly maintain and update a submodule are tricky and not well known. So it might be simpler to just include the examples directly in ml5-library rather than importing as a submodule. That said I'm totally open to it!

An important priority from my point of view is ease of people finding the examples on the website and being able to run them in the web editor (and keeping the web editor up to date). So I would go with whatever solution makes building the library, website, and pushing examples to the web editor easiest!

Hope this helps a bit! Yay!

[bomanimc]

Put up a PR with the proposed changes: #831! While I was doing it, I recognized that I still have one major concern about the direction this change would take the library.

My primary concern is the separation of the code for the examples and the website code. Assuming that the examples remain quite simple, this isn't a major problem. But in a future where the experience we want to provide through the examples becomes more complex, it might take more and more non-library-code to further development of the library, which could continue to bloat the repo size. Say, for example, we wanted to add some more complicated UI components to the examples pages, we might want to include React and some other libraries. I'm also thinking about cases where we might want to make the design of the examples site more consistent with the main website. I figure that it'd probably be good to think about this issue before landing #831 and archiving the examples repository.

A solution to some of the issues here could be to create separate libraries that would include shared resources that we want to keep in sync across the main site and the examples site (for example, an NPM module for a ml5 design system and component library, etc).

All that said, I'm not sure if/when we'll ever reach a point where the examples will be complex enough to make this a major concern. @yining1023 or @AndreasRef, maybe you two have thoughts on this!

Please let me know what y'all think!

[AndreasRef]

Hey @bomanimc and all :-)

For the work I am doing in my fellowship with creating more examples I don't think it will be a concern: The examples will be all pretty simple. I will use no external UI components or other libraries. Only exception will perhaps be one or two examples that include libraries listed on https://p5js.org/libraries/

[bomanimc]

Thanks @AndreasRef!

Also listing some of the steps that we'd want to take should we decide to move forward with this plan:

On the ml5-examples repository:

1. (Potentially) Announce plans for changes to the repository over communication channels with people who use or contribute to ml5.js.
2. ml5-examples: Merge or close all of the open pull requests.
3. ml5-library: Update the bomani.add-examples branch with a copy of the latest changes to the ml5-examples repo.
4. ml5-library: Merge changes from bomani.examples-monorepo-test into bomani.add-examples.
5. ml5-library: Merge changes from bomani.add-examples into development.
6. ml5-library: Merge changes from this branch into the release branch This step completes the change to add examples to this repository.
7. ml5-library: Deploy a version of the ml5 examples index based on the code in this repo.
8. ml5-examples: Update the ml5 examples index deployed through this directory to redirect (either automatically or by making the site say "The examples now live at...")
9. ml5-examples: Update the README to denote that the repo has been deprecated.
10. ml5-examples: Archive the repository, preventing further changes to the codebase and signaling to viewers that the repo has been closed.
11. ml5-examples: Transfer all of the issues to the ml5-examples repo: https://help.github.com/en/github/managing-your-work-on-github/transferring-an-issue-to-another-repository
12. ml5-library: Since many of the issues on the ml5-examples repo were addressed by changes to ml5-library or have corresponding issues, we should go through the new issues that have been moved from ml5-examples to close/label/triage these issues.

For step 1, I'd love to get feedback on if this is necessary and the best way to communicate with the community!

Please let me know if there's anything I'm overlooking here!

[bomanimc]

Done! The ml5-examples is now archived and the ml5-library now contains the examples folder. There are still more changes needed to get the development workflow here to be as smooth as possible, but hopefully this will be a step in the process.

Thanks for all of your help so far!