Skip to content

docs: reorganize contribute to blockly docs#10188

Open
zspriggs wants to merge 18 commits into
RaspberryPiFoundation:mainfrom
zspriggs:contributing
Open

docs: reorganize contribute to blockly docs#10188
zspriggs wants to merge 18 commits into
RaspberryPiFoundation:mainfrom
zspriggs:contributing

Conversation

@zspriggs

Copy link
Copy Markdown
Contributor

The basics

The details

Resolves

Fixes #10137

Proposed Changes & Reasons for Changes

Section: Get Started

  • Deleted pr_review_process, with content merged into write_a_good_pr
    • Edited down the content in write_a_good_pr to make it more succinct, and combined redundant steps of the pr_review_process material.
    • New version essentially tells the story of a PR from start to merge
  • Reorganized write_a_good_issue
    • Previously, this doc separated the steps for “Feature Request” and “Bug” so that the document felt a little repetitive, since some of the steps are essentially the same. There also wasn't info on filing a documentation issue.
    • Now the document is organized so that Feature Request/Bug/Documentation all share the common steps, but each also have their own description.
  • Deleted issue_labels page
    • A lot of this content was made stale by recent changes to our issue labels
    • Added some info about issue_labels to both write_a_good_pr and write_a_good_issue
  • Moved playground and development_tools into Contribute to Core section
    • Both of these are more largely applicable than first time contribution and therefore should live in Contribute to Core rather than Get Started

Section: Contribute to Core

  • Added a new doc, core_tour to Core Architecture folder
    • This doc goes primarily goes through an overview of the file/folder structure of core and docs.
    • It also includes information about the separation between the render and data management since many classes are essentially split into two (e.g. Block and BlockSvg) and it may not be obvious to someone new to Blockly that this split exists (or why it exists).
    • This doc also explicitly states how to run Blockly headless, which as far as I could tell isn't anywhere in our docs currently
  • Combined pages add_localization_token, translating, and klingon.
    • The “Klingon” section was slightly cut down from the original, the others are unchanged from their original form.
    • Since these pages are now combined, the folder they lived in (Localization) was removed
    • In the future, we should make a more natural place for the Klingon section to live, since it doesn't really fit super well in a contributing-focused doc, but doesn’t really have a proper home anywhere else in our documentation.
  • unit_testing and playground are now in their own subfolder within Contribute to Core called Testing
  • advanced and building are also now in their own subfolder within Contribute to Core called Building and Compilation.

Also changed sidebars.js and _redirects to reflect all of these changes.

Test Coverage

N/A, but tested all links

Additional Information

Contribute to Samples docs remain untouched. These docs will need to be changed again a decent amount once the samples are moved into core (#7755), so major changes can/should wait until then so that we don't have to do two major overhauls of these docs in a row.

@zspriggs
zspriggs requested a review from a team as a code owner July 24, 2026 15:18
@zspriggs
zspriggs requested a review from mikeharv July 24, 2026 15:18
@zspriggs zspriggs changed the title docs: reorganize contribute to blockly docs docs: reorganize contribute to blockly docs Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Streamline "Contribute to Blockly" docs

2 participants