[devOps] Centralize version release process to single-repo changes

[bomanimc]

This issue extends a conversation discussed in #387.

Context: Current Methodology

The ml5.js project’s public-facing resources are a confluence of a few different sub-projects that each address a different focus within the overall usability of the library. With regards to devops, the four primary libraries are:

• ml5-library
• ml5-examples
• ml5-website
• ml5-boilerplate

When a new release of the core library (e.g. 0.4.2 → 0.4.3) is launched, each of the other repos needs to be updated to use the latest version number in the documentation, code examples, etc as well. A goal in this process is to have the version number for the repository explicitly listed on all the imports, rather than allowing imports with UNPKG to silently default to the latest version, which is believed to be helpful for support and debugging. This means that there’s a time-consuming, multi-faceted process that can be quite difficult for new members on the project to take on. The process is as follows (see release process issue by Joey for further discussion #387):

Updating the Core ml5.js Library (ml5-library - Published w/ NPM & served w/ UNPKG):

• Create a new branch off of the development (default) branch
• In the new branch, change the version number in package.json and commit the changes
• Create a new PR with the version number change and approve it’s merged into the development branch
• Ensure that everything looks good on the development branch by checking the results of the Travis CI checks that run on the PR, and then merge the development branch into the release branch locally.
• Locally run all of the build steps to create a new distribution.
• Run npm publish to upload the minified distribution to npm (from which it will be served to users of the library via UNPKG or through npm install)
• Also push to the gh-pages branch to update the ml5 examples repo.

Updating the ml5.js Examples (ml5-examples - Deploys with GitHub Pages):

• Create a new branch off of the development (default) branch
• In the new branch, run a script to change all of the references to the core library version to the latest version and then commit the changes (Example PR).
• Merge the changes into the development branch.
• Ensure that everything looks good on the development branch and then merge the development branch into the release branch.
• Future Requirements:
  • Push all of the examples to p5.js Web Editor automatically using API keys
  • Make a PR to update the version of the library used in the Teachable Machine project (separate repo)

Updating the ml5.js Website (ml5-website - Deploys with Netlify):

• Create a new branch off of the master branch named after the new version number
• In the new branch, manually change the static references to the core library version to the latest version and then commit the changes (Example PR)
• Merge the changes into master, which triggers a deployment to Netlify.

Updating the ml5.js Boilerplate (ml5-boilerplate):

• Update the version number in the ml5 import (either by directly committing to the repo or by creating and merging a branch (Example Commit).

Next Steps

Updating this thread with details and associating PRs and issues with similar levels of documentation and context!

[bomanimc]

Our first win in the release process: @joeyklee archived the ml5-boilerplate repo, which removes one of the four repos involved in the original release process. 4 -> 3!

[bomanimc]

Secondly, we decided to switch over to using @latest in our examples, which cuts the updates to the ml5-examples repo out of our version release process. The two PRs that executed these changes are:

• Part 1: Update ml5 reference script to use @latest ml5-examples#267
• Part 3: Replace references to ml5 0.4.3 library version with @latest ml5-examples#268

3 -> 2!

[bomanimc]

We also switched over to using a version badge on the ml5-website repo, which cuts out the manual update process for the website! Those changes are in #811

That's 2 -> 1, which completes the primary goal for these changes!

Next, I'll work on some improvements to the release workflow in the repository.

[joeyklee]

@bomanimc - Your documentation of the progress and approaches are so helpful for explaining the decision making process behind each of these changes! Bravo!

[shiffman]

Wonderful ditto everything @joeyklee said! Related to my comment in #809, I'd like to highlight the following as a priority!

Push all of the examples to p5.js Web Editor automatically using API keys

💖💫

[bomanimc]

Re-opening this issue because we're not quite centralized! The ml5-examples repo still presents challenges in the release process because we need to coordinate a new deployment of examples that have been added/edited (in correspondence with library changes) when we release a new versions. This means that we're still required to work with two repos to make a change. Hopefully, #809 can help us to address this.

[bomanimc]

#809 is complete, so we can also close this task. Making a release of the library now only requires changes to this repository. Next, we can work on making the process of cutting a release even easier by simplifying our branches and versioning processes.