We welcome contributions of all kinds — whether it’s code, 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 below, then explore open issues or discussions to find a place to contribute.
Music Blocks is being built from the ground-up, to address several architectural problems with this run. Since Music Blocks is a fork of Turtle Blocks JS, musical functionality was added on top of it. However, music is fundamental to Music Blocks. Besides, the Turtle Blocks JS started initially with handful of features and was written without a complex architecture. As Music Blocks was built on top of that, it became incrementally complex, but the architecture remained simple, thus resulting in a monolith. Also, the functionality is tightly coupled with the interface and native client API (Web API).
Keeping these problems in mind, we have considered a foundational rebuild that will address all these issues, whilst adding buffers for future additions. Additionally, we will make use of a more elegant tech-stack to develop and maintain this project given its scale. After the core is built, we'll be porting features from this application to it.
Refer to the repository sugarlabs/musicblocks-v4 for more information about the new project — Music Blocks 4.0.
Music Blocks is a Web Application and is written using browser
technologies — HTML, CSS (SCSS), JavaScript, SVG, etc.
If you're just getting started with development, you may refer to the following resources:
- HTML tutorial - w3schools.com
- HTML reference - MDN Web Docs
- CSS tutorial - w3schools.com
- CSS reference - MDN Web Docs
- JavaScript tutorial - w3schools.com
- JavaScript reference - MDN Web Docs
For code contributions, please follow these general guidelines for contributions.
Follow AI guidelines for Sugar Labs
AI-assisted development tools (such as GitHub Copilot, ChatGPT, Cursor, Claude, or similar systems) may be used to support contributions. However, contributors remain fully responsible for any code they submit.
When using AI tools, please follow these guidelines:
- Understand the code - Do not submit code that you do not fully understand. Contributors must be able to explain and maintain their changes.
- Review carefully - AI-generated code can contain errors, security issues, or incorrect assumptions. Always review outputs critically.
- Follow project conventions - Ensure that generated code matches the existing coding style, architecture, and design patterns used in the repository.
- Test thoroughly - AI-assisted changes must pass all project checks. Run linting, formatting, and test commands before submitting.
- Avoid large blind changes - Large-scale automated modifications should be reviewed incrementally and preferably split into smaller, focused pull requests.
- Licensing awareness - Ensure that generated content does not introduce incompatible licensed material or copied external code without attribution.
- Architecture awareness - Prefer small, incremental AI-assisted changes that align with existing architecture rather than large structural rewrites.
Mentioning AI assistance in your pull request description is optional but encouraged for transparency.
AI tools such as ChatGPT, Copilot, or other LLMs may assist contributors in understanding the codebase or drafting code changes. However, contributors remain fully responsible for the code they submit.
When using AI tools:
- Ensure you understand the generated code before including it in a pull request.
- Verify that the code follows project style and architecture.
- Avoid submitting large AI-generated patches without manual review.
- Run linting, formatting, and tests before submitting changes.
- Ensure the generated code does not introduce licensing issues.
If AI tools were used while preparing a pull request:
- Clearly review and test all generated changes.
- Keep pull requests small and focused.
- Avoid submitting unrelated modifications suggested by AI.
- Be prepared to explain the reasoning behind the changes during review.
AI tools should assist development, but they should not replace understanding of the codebase.
Run these commands locally before submitting a PR:
npm run lint # ESLint
npx prettier --check . # Formatting
npm test # JestNOTE: Only run prettier on the files you have modified.
If formatting fails, run npx prettier --write . to fix it.
Follow these steps when contributing:
-
Create a new branch
git checkout -b docs/issue-number-short-description -
Make your changes following project guidelines.
-
Run required checks before pushing:
npm run lint npx prettier --check . npm test -
Commit with clear, descriptive messages:
git commit -m "docs: add AI contribution guidelines (Related to #XXXX)" -
Push your branch:
git push origin branch-name -
Open a Pull Request:
- Use a clear and descriptive title.
- Link the related issue using
Related to #XXXXorPartially addresses #XXXX. - Explain what changed and why.
- Keep pull requests focused on a single topic or feature.
-
Respond to review feedback and update your branch as needed.
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.
Music Blocks is licensed under the AGPL. If you add a new file to the Music Blocks code base, please be sure to include a license header as per below:
/**
* MusicBlocks v3.6.2 (ADD THE UP-TO-DATE VERSION)
*
* @author Walter Bender (MODIFY THE AUTHOR AS NEEDED)
*
* @copyright 2025 Walter Bender (MODIFY THE AUTHOR AND YEAR AS NEEDED)
*
* @license
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/This header must be added at the top of all source code files to ensure compliance with the project's open-source license.
Music Blocks uses PO files to maintain translations of the text strings used in the interface. The PO files are available through an interactive website.
Alternatively, translators can clone the git repo, edit the PO files locally, and make a pull request.
Note that once the PO files are updated, they are compiled into an INI file, which is the file used by Music Blocks.
Use the discussions tab at the top of the repository to:
- Ask questions you’re wondering about.
- Share ideas.
- Engage with other community members.
Feel free. But, please don't spam :p.
-
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.
-
Use labels on your issues and PRs.
-
Please do not spam with many PRs consisting of little changes.
-
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.
-
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.
-
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 #ticketnoorcloses #ticketnoin the PR's comment. Briefly explain what your PR is doing. -
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.
-
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.
-
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 tab on top the the repository, or the Sugar-dev Devel <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.
-
Work on things that matter. Follow three milestones:
Port Ready,Migration, andFuture. Those taggedPort Readyare priority. Those tagged withMigrationwill be taken care of during or after the foundation rebuild. Feel free to participate in the conversation, adding valuable comments. Those tagged withFutureneed 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).