updating all documentation

mitmedialab · Jul 29, 2024 · c3137ab · c3137ab
1 parent fd6d6c5
commit c3137ab
Show file tree

Hide file tree

Showing 6 changed files with 143 additions and 130 deletions.
diff --git a/CI-CD.md b/CI-CD.md
@@ -0,0 +1,56 @@
+# Continuous Integration & Deployment
+
+If you followed the steps outlined in the README's [Making an Extension](./README.md#🔨-making-an-extension) section, you should have created a new branch off of the `dev` branch where you implemented your extension. 
+
+## Automatic Deployment to Temperorary URL
+
+Whenever you [push]() on this new branch, a [github action]() will automatically deploy your extension to a URL corresponding to your branch name. 
+
+For example, if my branch is called `myNewExtension`, whenever I succesfully push up code on this branch, I should be able to see my changes at: https://playground.raise.mit.edu/myNewExtension/
+
+> NOTE: The github action(s) that manages deployment can take anywhere from 10 - 30 minutes. View the status of actions in the repo's [Actions tab](https://github.com/mitmedialab/prg-extension-boilerplate/actions). In order for your site to be succesfully deployed, both an action titled with your commmit message and one after it titled ***pages build and deployment*** must complete succesfully. 
+
+Though this branch-specific URL can be very helpful for sharing your extension quickly, we **require** that you don't use this URL for _official_ purposes -- instead you should follow the instructions in [Integrating Your Extension into the main Branch](#integrating-your-extension-into-the-main-branch) if you want to share extension as part of a curricullum, to an outside organization, etc. 
+
+So this means you can use your branch-specific URL to share your extension with colleagues, get feedback, and quickly iterate on your extension. However, if you want to share your extension externally, especially with students, it must first be integrated into the `main` branch, and then you can direct them to: https://playground.raise.mit.edu/main/
+
+## Integrating Your Extension into the `main` Branch
+
+The extensions pushed into the `main` branch should represent all of the extensions PRG officially supports, and thus what PRG is committed to maintaining now and into the future. 
+
+Thus, you should only _officially_ share extensions via the `main` branch and corresponding [main site](https://playground.raise.mit.edu/main/) (https://playground.raise.mit.edu/main/). In other words, if an outside party (student, teacher, organization, etc.) reports a bug about an extension (or the platform), they should be doing so based on their usage of the main site -- not a branch-specific site that no other team members know about. 
+
+By adhering to this practice, as well as a regimented process for [merging](https://git-scm.com/docs/git-merge) changes to the `dev` and `main` branches, we can ensure both the best experinece for our users and the least amount of headache for us as developers / maintainers.
+
+Here's the process for getting your extension into the `main` branch and deployed to https://playground.raise.mit.edu/main/:
+
+1. Get your development branch current with the `dev` branch
+    ```bash
+    cd prg-extension-boilerplate/ # Change directory (cd) to prg-extension-boilerplate/, if not already there
+
+    git checkout <your branch name> # Checkout your brnahc, if not already checked out
+
+    git pull # Fetch the latest changes from all remote branches. 
+    # NOTE: using `git fetch` would do the same, but it's yet another git command to remember...
+
+    git merge origin/dev # Merge the latest changes from the remote (i.e. origin) dev branch into your development branch
+    ```
+2. Create a Pull Request (PR) from your branch into `dev`
+    1. Go to the [Pull Requests tab](https://github.com/mitmedialab/prg-extension-boilerplate/pulls)
+    2. Click **New Pull Request** 
+    3. Set _base_ to `dev` and _compare_ to the name of your branch
+        - The flow should look like: `dev` <-- `<your branch>`
+    4. Select **Create Pull Request** 
+        - Do this enough times so that the pull request is actually created -- github's UI seems to be a little redunant
+3. Set [pmalacho-mit](https://github.com/pmalacho-mit) (Parker Malachowsky) as the reviewer of the PR
+    - NOTE: If anyone's interested in being a reviewer please also talk to Parker and he will add you above.
+4. Work with your reviewer to get your PR approved, and then **YOUR REVIEWER** will merge your PR and your changes will go into `dev` 🎉🎉🎉.  In this way, you and the reviewer are equally responsible for keeping the `dev` branch bug-free. 
+    - Your reviewer will review your code, test your extension, and leave comments for you to respond to.
+    - You can speed up the review process by doing the following:
+        - Writing readable code and leaving necessary (but [_only necessary_](https://levelup.gitconnected.com/please-dont-comment-your-code-d0830785bdc9)) comments
+            - Use [JSDoc comments](https://jsdoc.app/about-getting-started.html) where possible (e.g. on functions, classes, method parameters, etc.)
+        - [Writing tests for your extension]() (coming soon)
+        - [Creating tutorials for your extension]() (coming soon)
+5. Once your code is in `dev`, your work is done! The code base's maintainer (Parker, at this time) will then semiweekly merge the `dev` branch into the `main` branch.
+6. Once Parker has notified you that your changes are live, you can direct your audience to the deployed `main` branch: https://playground.raise.mit.edu/main/
+    - Check out the [URL Parameters]() section to see how you can customize this link to automatically add your extension, tutorials, demo project, etc. when the page is loaded. 
diff --git a/README.md b/README.md
@@ -1,10 +1,14 @@
-# ✨ PRG Scratch Extension Development Environment
+# ✨ PRG RAISE Playground
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mitmedialab/prg-extension-boilerplate/tree/dev)
 
 This repository is your one-stop-shop for developing [scratch extensions](https://en.scratch-wiki.info/wiki/Extension) for PRG curricula.
 
-It's a fullblown [fork](https://en.wikipedia.org/wiki/Fork_(software_development)) of the official Scratch codebase, which the [Personal Robotics Group](https://robots.media.mit.edu/) (PRG) manages and extends to meet its needs. 
+It [forks](https://en.wikipedia.org/wiki/Fork_(software_development)) a few of the official Scratch codebases, which the [Personal Robotics Group](https://robots.media.mit.edu/) (PRG) manages and extends to meet its needs. These exist as [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) located inside of the [scratch-packages/](./scratch-packages/) folder.
+- [scratch-packages/scratch-gui/](./scratch-packages/scratch-gui/)
+    - [prg-raise-playground-scratch-gui](https://github.com/mitmedialab/prg-raise-playground-scratch-gui) forks the [scratch-gui](https://github.com/scratchfoundation/scratch-gui) package. See [our changes](https://github.com/mitmedialab/prg-raise-playground-scratch-gui/pull/7).
+- [scratch-packages/scratch-vm/](./scratch-packages/scratch-vm/)
+    - [prg-raise-playground-scratch-vm](https://github.com/mitmedialab/prg-raise-playground-scratch-vm) forks the [scratch-vm](https://github.com/scratchfoundation/scratch-vm) package. See [our changes](https://github.com/mitmedialab/prg-raise-playground-scratch-vm/pull/2).
 
 Looking for the old documentation (<= Sept. 2022)? Head [here](./BACKGROUND.md).
 
@@ -14,7 +18,7 @@ Looking for the old documentation (<= Sept. 2022)? Head [here](./BACKGROUND.md).
 
 ## ⚡ Quick Start
 
-This section contains concise explanations on how to accomplish something (often just a couple of commands to run). If you need more info please check out one of the lower sections. 
+This section contains concise explanations on how to accomplish something (often just a couple of [terminal commands](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line) to run). If you need more info please check out one of the lower sections. 
 
 ### 🚧 Project setup
 
@@ -41,7 +45,7 @@ git checkout dev
 pnpm install
 # This will symlink the packages together to allow for seamless local development, and installs dependencies for each package. 
 # This should only need to be ran once (unless you checkout a branch that adds new package dependencies).
-# Takes ~1.5 minutes
+# Takes ~1.5 minutes the first time it runs, and is much quicker (a few seconds) for later installs / updates
 
 pnpm dev -i examples
 # This starts up a development server, serving the two "example" extensions.
@@ -103,60 +107,7 @@ As long as the development server is running (meaning the `pnpm dev` command is
 
 ### 📦 Committing, pushing, and deploying an extension 
 
-If you followed the steps outlined in [Making an Extension](#🔨-making-an-extension), you should have created a new branch off of the `dev` branch where you implemented your extension. 
-
-#### Automatic Deployment to Temperorary URL
-
-Whenever you [push]() on this new branch, a [github action]() will automatically deploy your extension to a URL corresponding to your branch name. 
-
-For example, if my branch is called `myNewExtension`, whenever I succesfully push up code on this branch, I should be able to see my changes at: https://playground.raise.mit.edu/myNewExtension/
-
-> NOTE: The github action(s) that manages deployment can take anywhere from 10 - 30 minutes. View the status of actions in the repo's [Actions tab](https://github.com/mitmedialab/prg-extension-boilerplate/actions). In order for your site to be succesfully deployed, both an action titled with your commmit message and one after it titled ***pages build and deployment*** must complete succesfully. 
-
-Though this branch-specific URL can be very helpful for sharing your extension quickly, we **require** that you don't use this URL for _official_ purposes -- instead you should follow the instructions in [Integrating Your Extension into the main Branch](#integrating-your-extension-into-the-main-branch) if you want to share extension as part of a curricullum, to an outside organization, etc. 
-
-So this means you can use your branch-specific URL to share your extension with colleagues, get feedback, and quickly iterate on your extension. However, if you want to share your extension externally, especially with students, it must first be integrated into the `main` branch, and then you can direct them to: https://playground.raise.mit.edu/main/
-
-#### Integrating Your Extension into the `main` Branch
-
-The extensions pushed into the `main` branch should represent all of the extensions PRG officially supports, and thus what PRG is committed to maintaining now and into the future. 
-
-Thus, you should only _officially_ share extensions via the `main` branch and corresponding [main site](https://playground.raise.mit.edu/main/) (https://playground.raise.mit.edu/main/). In other words, if an outside party (student, teacher, organization, etc.) reports a bug about an extension (or the platform), they should be doing so based on their usage of the main site -- not a branch-specific site that no other team members know about. 
-
-By adhering to this practice, as well as a regimented process for [merging](https://git-scm.com/docs/git-merge) changes to the `dev` and `main` branches, we can ensure both the best experinece for our users and the least amount of headache for us as developers / maintainers.
-
-Here's the process for getting your extension into the `main` branch and deployed to https://playground.raise.mit.edu/main/:
-
-1. Get your development branch current with the `dev` branch
-    ```bash
-    cd prg-extension-boilerplate/ # Change directory (cd) to prg-extension-boilerplate/, if not already there
-
-    git checkout <your branch name> # Checkout your brnahc, if not already checked out
-
-    git pull # Fetch the latest changes from all remote branches. 
-    # NOTE: using `git fetch` would do the same, but it's yet another git command to remember...
-
-    git merge origin/dev # Merge the latest changes from the remote (i.e. origin) dev branch into your development branch
-    ```
-2. Create a Pull Request (PR) from your branch into `dev`
-    1. Go to the [Pull Requests tab](https://github.com/mitmedialab/prg-extension-boilerplate/pulls)
-    2. Click **New Pull Request** 
-    3. Set _base_ to `dev` and _compare_ to the name of your branch
-        - The flow should look like: `dev` <-- `<your branch>`
-    4. Select **Create Pull Request** 
-        - Do this enough times so that the pull request is actually created -- github's UI seems to be a little redunant
-3. Set [pmalacho-mit](https://github.com/pmalacho-mit) (Parker Malachowsky) as the reviewer of the PR
-    - NOTE: If anyone's interested in being a reviewer please also talk to Parker and he will add you above.
-4. Work with your reviewer to get your PR approved, and then **YOUR REVIEWER** will merge your PR and your changes will go into `dev` 🎉🎉🎉.  In this way, you and the reviewer are equally responsible for keeping the `dev` branch bug-free. 
-    - Your reviewer will review your code, test your extension, and leave comments for you to respond to.
-    - You can speed up the review process by doing the following:
-        - Writing readable code and leaving necessary (but [_only necessary_](https://levelup.gitconnected.com/please-dont-comment-your-code-d0830785bdc9)) comments
-            - Use [JSDoc comments](https://jsdoc.app/about-getting-started.html) where possible (e.g. on functions, classes, method parameters, etc.)
-        - [Writing tests for your extension]() (coming soon)
-        - [Creating tutorials for your extension]() (coming soon)
-5. Once your code is in `dev`, your work is done! The code base's maintainer (Parker, at this time) will then semiweekly merge the `dev` branch into the `main` branch.
-6. Once Parker has notified you that your changes are live, you can direct your audience to the deployed `main` branch: https://playground.raise.mit.edu/main/
-    - Check out the [URL Parameters]() section to see how you can customize this link to automatically add your extension, tutorials, demo project, etc. when the page is loaded. 
+To learn how to manage git-tracking and deploying your extension, please head to the [CICD.md](./CI-CD.md) (continuous integration & continuous delivery / deployment) documentation.
 
 ## 🔎 How to program an extension
 
@@ -170,7 +121,7 @@ Also, try hovering over fields to view their documentation (typically a [summary
 
 ![Gif of video hovering over fields to peak documentation](//.assets/hover.gif)
 
-Still stuck? Check out our [From 0 to Extension guide](#-from-0-to-extension) and/or contact more experienced extension developers, like [Parker](https://github.com/pmalacho-mit) or [Randi](https://github.com/randi-c-dubs)
+Still stuck? Check out our [From 0 to Extension guide](#-from-0-to-extension) and/or contact more experienced extension developers, like [Parker](https://github.com/pmalacho-mit) or [Maya](https://github.com/mayarajan3)
 
 ### 🪜 From 0 to Extension
 

diff --git a/extensions/src/.templates/default.ts b/extensions/src/.templates/default.ts
@@ -1,16 +1,16 @@
-import { ArgumentType, BlockType, BlockUtilityWithID, Environment, ExtensionMenuDisplayDetails, extension, scratch } from "$common";
-import BlockUtility from "$scratch-vm/engine/block-utility";
+import { scratch, extension, type ExtensionMenuDisplayDetails, type BlockUtilityWithID, type Environment } from "$common";
 
 /** 👋 Hi!
 
 Below is a working Extension that you should adapt to fit your needs. 
 
 It makes use of JSDoc comments (anything inside of the '/**   * /' regions) 
 to add explanations to what you're seeing. These do not affect the code 
-and can be delete when you no longer need them.
+and can be deleted whenever you no longer need them.
 
 Anywhere you find something that looks like: @see {ExplanationOfSomething} 
-hover over the 'ExplanationOfSomething' part to get a popup that tells you more about the code.
+hover over the 'ExplanationOfSomething' part (the text inside of the {...} curly brackets) 
+to get a popup that tells you more about that concept.
 
 Try out hovering by reviewing the below terminology.
 NOTE: When the documentation refers to these terms, they will be capitalized.
@@ -33,37 +33,46 @@ const details: ExtensionMenuDisplayDetails = {
 };
 
 /** @see {ExplanationOfClass} */
-/** @see {ExplanationOfInitMethod} */
 export default class ExtensionNameGoesHere extends extension(details) {
 
+  /** @see {ExplanationOfInitMethod} */
   init(env: Environment) {
     this.exampleField = 0;
   }
 
   /** @see {ExplanationOfField} */
   exampleField: number;
 
-  /** @see {ExplanationOfBlockType} */
-  /** @see {ExplanationOfReporterBlock} */
-  @(scratch.reporter`This increments an internal field and then reports it's value`)
+  /** @see {ExplanationOfExampleReporter}*/
+  @(scratch.reporter`This is the block's display text (so replace me with what you want the block to say)`)
   exampleReporter() {
     return ++this.exampleField;
   }
-
-  /** @see {ExplanationOfCommandBlock} */
-  @(scratch.command(
-    (instance, $) => 
-      /** @see {ExplanationOfBlockArg} */
-      $`This is the block's display text with inputs here --> ${"string"} and here --> ${{type: "number", defaultValue: instance.exampleField}}`
-  ))
-  exampleCommand(exampleString: string, exampleNumber: number) {
-    alert(`This is a command! Here's what it received: ${exampleString} and ${exampleNumber}`); // Replace with what the block should do! 
+
+  /** @see {ExplanationOfReporterWithArguments}*/
+  @(scratch.reporter`This is the block's display text with inputs here --> ${"string"} and here --> ${{ type: "number", defaultValue: 1 }}`)
+  reporterThatTakesTwoArguments(exampleString: string, exampleNumber: number) {
+    return exampleString + exampleNumber;
+  }
+
+  /** @see {ExplanationOfExampleCommand} */
+  @(scratch.command`This is the block's display text`)
+  exampleCommand() {
+    alert("This is a command!");
+  }
+
+  /** @see {ExplanationOfCommandWithExtendDefinition} */
+  @(scratch.command((instance, tag) => {
+    console.log("Creating a block for extension: ", instance.id);
+    return tag`This is the block's display text`;
+  }))
+  exampleCommandWithExtendedDefinition() {
+    alert("This is a command defined using the extended definition strategy!");
   }
 
-  /** @see {ExplanationOfHatBlock} */
+  /** @see {ExplanationOfExampleHatAndBlockUtility} */
   @(scratch.hat`Should the below block execute: ${"Boolean"}`)
-  /** @see {ExplanationOfBlockUtilityWithID} */
-  async exampleHat(condition: boolean, util: BlockUtilityWithID) {
+  async exampleHatThatUsesBlockUtility(condition: boolean, util: BlockUtilityWithID) {
     return util.stackFrame.isLoop === condition;
   }
 }
diff --git a/extensions/src/common/extension/decorators/taggedTemplate.ts b/extensions/src/common/extension/decorators/taggedTemplate.ts
@@ -1,6 +1,6 @@
 import { BlockMetadata, Argument, ReturnTypeByBlockType, ScratchBlockType, NoArgsBlock, OneArgBlock, BlockUtilityWithID, InlineImage, InlineImageSpecifier } from "$common/types";
 import { block } from "$common/extension/decorators/blocks";
-import { ExtensionInstance } from "..";
+import { extension, ExtensionInstance } from "..";
 import { TypedMethodDecorator } from ".";
 import type BlockUtility from "$scratch-vm/engine/block-utility";
 
@@ -84,5 +84,9 @@ export const scratch = {
     reporter: makeDecorator("reporter"),
     command: makeDecorator("command"),
     button: makeDecorator("button"),
-    hat: makeDecorator("hat")
+    hat: makeDecorator("hat"),
+    boolean: makeDecorator("Boolean"),
+    conditional: makeDecorator("conditional"),
+    event: makeDecorator("event"),
+    loop: makeDecorator("loop"),
 }
diff --git a/extensions/src/common/globals.ts b/extensions/src/common/globals.ts
@@ -5,7 +5,7 @@ export const AuxiliaryExtensionInfo = "AuxiliaryExtensionInfo";
 
 /**
  * Literal values that control the interaction between the extension framework and the Scratch GUI,
- * specifically how dropdowns (tied to dynamic menus) are co-opted to support custom block arguments.
+ * specifically how dropdowns (tied to dynamic menus) are co-opted to support custom block arguments (and their UIs).
  */
 export const guiDropdownInterop = {
     runtimeKey: "prgDropdownCustomization",