Proposal: Encourage New Contributors to Create a Music Blocks Project First Before Contributing

[patilpratik1905]

Background

Music Blocks receives many pull requests, including some that are small, overlapping, or lack enough understanding of the user experience. This increases review load and can make it harder for maintainers to focus on high-impact contributions.

Existing maintainer guidance already encourages new contributors to use Music Blocks and create a project before working on the codebase:

• First tip for new contributors: Create a project with Music Blocks
• I want to contribute. How can I get started?

The goal of this proposal is to turn that advice into a clearer, lightweight onboarding path.

This is intended to complement discussions about PR limits, review queues, CI, and automated review tools. Those tools improve review after a PR exists; this proposal aims to improve contributor context before a PR is opened.

Proposal

New contributors would be encouraged to create or remix a small Music Blocks project before making their first code contribution.

The purpose is to help contributors:

• Understand Music Blocks from a learner/user perspective.
• Learn the palettes, blocks, saving/loading, Planet, and widgets.
• Discover genuine usability problems, documentation gaps, or bugs.
• Connect a future PR to a concrete user need.
• Share creative work with the community.

A project does not need to be large or completely original. It could be a short melody, rhythm, visual experiment, game, interactive activity, or even a remix of an existing Music Blocks example. However, contributors are encouraged to explore and build beyond the basics, using a variety of Music Blocks components, as this helps develop a broader and more practical understanding of how the platform works.

This should improve contributor understanding without creating another review queue for maintainers. Creating and sharing a project should not automatically require a maintainer review, or a need to create a PR.

Resources for New Contributors

The following resources can help new contributors create a project and understand Music Blocks before working on the codebase:

• Music Blocks web application — create, run, save, load, export, and share projects.
• Using Music Blocks — explains the interface, toolbars, palettes, block help, saving/loading, Planet, and widgets.
• Music Blocks Programming Guide — explains pitch, rhythm, actions, music programming, widgets, and exports.
• Music Blocks examples — projects that can be explored, remixed, and used for inspiration.
• JavaScript Editor and API documentation — useful for contributors who want to connect block programming with JavaScript.
• Contributing guide — guidance for selecting work, testing, and submitting focused PRs.
• Music Blocks Discussions — questions, ideas, community discussion, and Show and tell.
• Music Blocks Matrix channel — a place to ask questions while making a project.

Suggested Project Sharing Format

If the community wants contributors to share their first project, a post could use this format:

Project link or attachment

[Planet link / exported HTML / screenshot]

What I made

A short description.

Features I used

For example: Rhythm, Pitch, Action, Widget, JavaScript Editor, etc.

What I learned or noticed

One thing that was confusing, surprising, useful, or possibly broken.

Possible follow-up

Link an existing issue, discussion, or explain whether I plan to investigate further.

Questions for Discussion

• Should creating a small Music Blocks project be a strong recommendation for new contributors, or a stricter part of the contribution process?

• Where should this guidance be highlighted?

  Existing places include:

  • First tip for new contributors
  • Getting started contributor discussion
  • CONTRIBUTING.md
  • Music Blocks documentation and examples

  Should it be added to one or more of these places, or should it be part of a community onboarding flow?

• Should there be any review or feedback for shared projects?

  A good project may reveal useful bugs, documentation gaps, examples, lesson ideas, or feature requests. At the same time, requiring maintainers to review every project may create a new workload. Would optional peer/community feedback be more suitable?

• Where should projects be shared?

  Would the existing Show and tell category be the right place, or should projects be shared through Planet, Matrix, blog posts, or another format?

• Would a separate First-time contributor label be useful for identifying and helping first-time PR authors?

  A separate label could be added and applied manually or through future automation. Would that be useful, or would it create unnecessary categorization?

• If a stricter approach is preferred, should a first-time contributor be asked to include a link to their Music Blocks project or Show and tell post in their first PR description?

  This would need careful consideration. GitHub's normal PR template is shared by all contributors, so a workflow specific to first-time contributors would require additional automation and should not be added unless maintainers agree that the benefit justifies the complexity.

Intended Outcome

The aim is not to make project creation a barrier to contributing.

The aim is to help contributors understand Music Blocks as users, discover meaningful problems, and submit fewer but more informed and useful contributions.

[walterbender]

See #8511