Ci/pr category check

.github/PULL_REQUEST_TEMPLATE/generic.md

@@ -15,6 +15,17 @@ about: Submit changes to the project for review and inclusion
 
 This PR fixes #
 
+## PR Category
+
+<!--- ⚠️ CI ENFORCED: You MUST check at least ONE category below or the CI will fail. -->
+<!--- Check all categories that apply to this pull request. -->
+
+-   [ ] 🐛 Bug Fix — Fixes a bug or incorrect behavior
+-   [ ] ✨ Feature — Adds new functionality
+-   [ ] ⚡ Performance — Improves performance (load time, memory, rendering, etc.)
+-   [ ] 🧪 Tests — Adds or updates test coverage
+-   [ ] 📝 Documentation — Updates to docs, comments, or README
+
 ## Changes Made
 
 <!--- Provide a summary of the changes made in this pull request. -->

.github/workflows/pr-category-check.yml

@@ -0,0 +1,113 @@
+name: PR Category Check
+
+# Ensures every PR has at least one category checkbox checked.
+# Automatically applies matching GitHub labels to the PR.
+# Uses pull_request_target so it works for fork PRs too (runs in base repo context).
+# This is safe because we only read the PR body from the event payload — no fork code is checked out or executed.
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  check-pr-category:
+    name: Validate PR Category & Auto-Label
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check categories and apply labels
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prBody = context.payload.pull_request.body || '';
+            const prNumber = context.payload.pull_request.number;
+
+            // Category checkboxes mapped to their GitHub label names
+            const categories = [
+              { label: 'Issue-Bug', emoji: '🐛', displayName: '🐛 Bug Fix', pattern: /- \[x\]\s*🐛\s*Bug Fix/i },
+              { label: 'Issue-Enhancement', emoji: '✨', displayName: '✨ Feature', pattern: /- \[x\]\s*✨\s*Feature/i },
+              { label: 'Issue-Performance', emoji: '⚡', displayName: '⚡ Performance', pattern: /- \[x\]\s*⚡\s*Performance/i },
+              { label: 'Issue-Testing', emoji: '🧪', displayName: '🧪 Tests', pattern: /- \[x\]\s*🧪\s*Tests/i },
+              { label: 'Issue-Documentation', emoji: '📝', displayName: '📝 Documentation', pattern: /- \[x\]\s*📝\s*Documentation/i },
+            ];
+
+            const checkedCategories = categories.filter(cat => cat.pattern.test(prBody));
+            const uncheckedCategories = categories.filter(cat => !cat.pattern.test(prBody));
+
+            // --- Step 1: Fail CI if no category is selected ---
+            if (checkedCategories.length === 0) {
+              const message = [
+                '## ❌ PR Category Required',
+                '',
+                'This pull request does not have any **PR Category** selected.',
+                'Please edit your PR description and check **at least one** category checkbox:',
+                '',
+                '| Category | Description |',
+                '|----------|-------------|',
+                '| 🐛 Bug Fix | Fixes a bug or incorrect behavior |',
+                '| ✨ Feature | Adds new functionality |',
+                '| ⚡ Performance | Improves performance |',
+                '| 🧪 Tests | Adds or updates test coverage |',
+                '| 📝 Documentation | Updates to docs, comments, or README |',
+                '',
+                'Example: Change `- [ ] 🐛 Bug Fix` to `- [x] 🐛 Bug Fix`',
+                '',
+                '> **Tip:** You can select multiple categories if your PR spans several areas.',
+              ].join('\n');
+
+              core.setFailed(message);
+              return;
+            }
+
+            // --- Step 2: Auto-apply labels for checked categories ---
+            const labelsToAdd = checkedCategories.map(cat => cat.label);
+            const labelsToRemove = uncheckedCategories.map(cat => cat.label);
+
+            // Get current labels on the PR
+            const { data: currentLabels } = await github.rest.issues.listLabelsOnIssue({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+            const currentLabelNames = currentLabels.map(l => l.name);
+
+            // Add labels that are checked but not yet on the PR
+            for (const label of labelsToAdd) {
+              if (!currentLabelNames.includes(label)) {
+                try {
+                  await github.rest.issues.addLabels({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: prNumber,
+                    labels: [label],
+                  });
+                  core.info(`🏷️ Added label: "${label}"`);
+                } catch (error) {
+                  core.warning(`⚠️ Could not add label "${label}". Make sure it exists in the repo. Error: ${error.message}`);
+                }
+              }
+            }
+
+            // Remove labels that are unchecked but still on the PR
+            for (const label of labelsToRemove) {
+              if (currentLabelNames.includes(label)) {
+                try {
+                  await github.rest.issues.removeLabel({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: prNumber,
+                    name: label,
+                  });
+                  core.info(`🗑️ Removed label: "${label}"`);
+                } catch (error) {
+                  core.warning(`⚠️ Could not remove label "${label}". Error: ${error.message}`);
+                }
+              }
+            }
+
+            const selected = checkedCategories.map(c => c.displayName).join(', ');
+            core.info(`✅ PR categories selected: ${selected}`);
+            core.info(`🏷️ Labels synced: ${labelsToAdd.join(', ')}`);

.github/workflows/pr-cypress-e2e.yml

@@ -0,0 +1,43 @@
+name: E2E Test
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+  push:
+    branches:
+      - master
+
+jobs:
+  e2e:
+    name: Run Cypress E2E Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Run Cypress E2E Tests
+        uses: cypress-io/github-action@v6
+        with:
+          install-command: npm ci
+          start: npm start
+          wait-on: 'http://127.0.0.1:3000'
+          wait-on-timeout: 120
+          browser: chrome
+          config: video=false
+
+      - name: Upload Cypress Screenshots on Failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cypress-screenshots
+          path: cypress/screenshots
+          if-no-files-found: ignore

CONTRIBUTING.md

@@ -1,17 +1,16 @@
 ## <a name="CONTRIBUTING"></a>Contributing
 
 We welcome contributions of all kinds — whether it’s code,
-documentation, music, lesson plans, artwork, or ideas.  Music Blocks
+documentation, music, lesson plans, artwork, or ideas. Music Blocks
 is a community-driven project, and every meaningful contribution helps
 improve the platform for learners and educators around the world.
 
 If you’re new to the project, start by setting up the local
-development environment using the guide linked above, then explore
+development environment using the guide linked below, then explore
 open issues or discussions to find a place to contribute.
 
 - [How to set up a local server](README.md#how-to-set-up-a-local-server)
 
-
 ### Special Notes
 
 Music Blocks is being built from the ground-up, to address several
@@ -50,9 +49,12 @@ following resources:
 - [JavaScript tutorial - w3schools.com](https://www.w3schools.com/js/default.asp)
 - [JavaScript reference - MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 
-Programmers, please follow these general [guidelines for
+For code contributions, please follow these general [guidelines for
 contributions](https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md).
 
+### AI guidelines
+
+Follow [AI guidelines for Sugar Labs](https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md#ai-guidelines-for-sugar-labs)
 
 ### Before You Push
 
@@ -64,8 +66,20 @@ npx prettier --check .    # Formatting
 npm test                  # Jest
 ```
 
+NOTE: Only run ```prettier``` on the files you have modified.
+
 If formatting fails, run `npx prettier --write .` to fix it.
 
+### After your PR is merged
+
+Please note that production deployments of Music Blocks are **manual**.
+
+This means that even after your pull request is merged, your changes may not immediately appear. Your update will become visible after the next official release is deployed.
+
+If your changes are not visible right away, it does **not** indicate a problem with your PR or implementation.
+
+This note is included to prevent contributors from spending time debugging caching or deployment issues unnecessarily.
+
 ### License Header
 
 Music Blocks is licensed under the [AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html).
@@ -129,60 +143,60 @@ Feel free. But, please don't spam :p.
 ### Keep in Mind
 
 1. Your contributions need not necessarily have to address any
-discovered issue. If you encounter any, feel free to add a fix through
-a PR, or create a new issue ticket.
+   discovered issue. If you encounter any, feel free to add a fix through
+   a PR, or create a new issue ticket.
 
 2. Use [labels](https://github.com/sugarlabs/musicblocks/labels) on
-your issues and PRs.
+   your issues and PRs.
 
 3. Please do not spam with many PRs consisting of little changes.
 
 4. If you are addressing a bulk change, divide your commits across
-multiple PRs, and send them one at a time. The fewer the number of
-files addressed per PR, the better.
+   multiple PRs, and send them one at a time. The fewer the number of
+   files addressed per PR, the better.
 
 5. Communicate effectively. Go straight to the point. You don't need
-to address anyone using '_sir_'. Don't write unnecessary comments;
-don't be over-apologetic. There is no superiority hierarchy. Every
-single contribution is welcome, as long as it doesn't spam or distract
-the flow.
+   to address anyone using '_sir_'. Don't write unnecessary comments;
+   don't be over-apologetic. There is no superiority hierarchy. Every
+   single contribution is welcome, as long as it doesn't spam or distract
+   the flow.
 
 6. Write useful, brief commit messages. Add commit descriptions if
-necessary. PR name should speak about what it is addressing and not
-the issue. In case a PR fixes an issue, use `fixes #ticketno` or
-`closes #ticketno` in the PR's comment. Briefly explain what your PR
-is doing.
+   necessary. PR name should speak about what it is addressing and not
+   the issue. In case a PR fixes an issue, use `fixes #ticketno` or
+   `closes #ticketno` in the PR's comment. Briefly explain what your PR
+   is doing.
 
 7. Always test your changes extensively before creating a PR. There's
-no sense in merging broken code. If a PR is a _work in progress
-(WIP)_, convert it to draft. It'll let the maintainers know it isn't
-ready for merging.
+   no sense in merging broken code. If a PR is a _work in progress
+   (WIP)_, convert it to draft. It'll let the maintainers know it isn't
+   ready for merging.
 
 8. Read and revise the concepts about programming constructs you're
-dealing with. You must be clear about the behavior of the language or
-compiler/transpiler. See [JavaScript
-docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
+   dealing with. You must be clear about the behavior of the language or
+   compiler/transpiler. See [JavaScript
+   docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
 
 9. If you have a question, do a _web search_ first. If you don't find
-any satisfactory answer, then ask it in a comment. If it is a general
-question about Music Blocks, please use the new
-[discussions](https://github.com/sugarlabs/musicblocks/discussions)
-tab on top the the repository, or the _Sugar-dev Devel
-<[sugar-devel@lists.sugarlabs.org](mailto:sugar-devel@lists.sugarlabs.org)>_
-mailing list. Don't ask silly questions (unless you don't know it is
-silly ;p) before searching it on the web.
+   any satisfactory answer, then ask it in a comment. If it is a general
+   question about Music Blocks, please use the new
+   [discussions](https://github.com/sugarlabs/musicblocks/discussions)
+   tab on top the the repository, or the _Sugar-dev Devel
+   <[sugar-devel@lists.sugarlabs.org](mailto:sugar-devel@lists.sugarlabs.org)>_
+   mailing list. Don't ask silly questions (unless you don't know it is
+   silly ;p) before searching it on the web.
 
 10. Work on things that matter. Follow three milestones: `Port Ready`,
-`Migration`, and `Future`.  Those tagged `Port Ready` are
-priority. Those tagged with `Migration` will be taken care of during
-or after the foundation rebuild. Feel free to participate in the
-conversation, adding valuable comments. Those tagged with `Future`
-need not be addressed presently.
+    `Migration`, and `Future`. Those tagged `Port Ready` are
+    priority. Those tagged with `Migration` will be taken care of during
+    or after the foundation rebuild. Feel free to participate in the
+    conversation, adding valuable comments. Those tagged with `Future`
+    need not be addressed presently.
 
 _Please note there is no need to ask permission to work on an
 issue. You should check for pull requests linked to an issue you are
 addressing; if there are none, then assume nobody has done
 anything. Begin to fix the problem, test, make your commits, push your
 commits, then make a pull request. Mention an issue number in the pull
 request, but not the commit message. These practices allow the
-competition of ideas (Sugar Labs is a meritocracy)._
+competition of ideas (Sugar Labs is a meritocracy)._