Need help with Technical documentations for beginners (get started guide) for blockly library.

[Krishna Nandula]

Hello,

I would like to understand the blockly library and start contributing to the project.

can any of the contributors guide me on where to start? are there any helpful documents for engineers to get started on contributing? A high-level understanding of various pieces of code etc.,

Thanks,

Krishna

[Jason Schanker]

Hi Krishna,

Welcome!  I'd start by getting an overview of Blockly by reviewing the Developer Guide at https://developers.google.com/blockly/guides/get-started/web .  When you want more details, you can refer to https://github.com/google/blockly/tree/master/core to view the methods and the implementations of the core classes (e.g., block.js and workspace.js), https://github.com/google/blockly/tree/master/blocks to see the code for the standard block definitions, and https://github.com/google/blockly/tree/master/generators for the code generators of the standard blocks.

You may also want to refer to the resources from Rachel's post at https://groups.google.com/g/blockly/c/19Hy5aLSzJY/m/klXgvXDvAAAJ , which recaps this year's Blockly Summit and includes a link to good first issues for beginners.  The Blockly Summit Link Party at https://groups.google.com/g/blockly/c/qFOjhROGDI0/m/4Ioc5qKNAAAJ also contains links to cool Blockly projects.

Hope this helps, and if you have any questions as you explore, you can always ask them here.  The Blockly community is very friendly and helpful!

Best,

Jason

[Maribeth Bottorff]

Hi, we'd love to have you contribute! Thanks Jason for providing some links! I have a few more to add :)

We do have some documentation on contributing to Blockly, in the Contributing section of the developer site: https://developers.google.com/blockly/guides/modify/contributing

There are pages on the tools Blockly uses, how our build process works, etc. Unfortunately, we don't have many docs that explain high-level concepts aimed at a contributor to the library. If you want to know about fields, there is a lot of documentation about them from an API consumer's point of view. But if you want to know for example how dragging a block from the flyout to the workspace works, well, there's not a lot of documentation about that besides reading the code. This is a weak spot in Blockly's documentation, but since I just joined the Blockly team a year ago, it was something I also found myself wishing for, and it's an area I'm hoping to make time to address soon (but we are a small team and it can be hard to find the time!)

I'll also say that blockly-samples might be an easier part of the codebase to start contributing in. It has fewer legacy issues than in the main blockly repo (you can use es6!) and some of the feature requests there can be worked on from the point of view of consuming the Blockly APIs (which tend to be more documented than the internal methods) rather than changing how core blockly works. Some of them do require changes in core blockly, so when you're ready for that, it's a good way to have a focused dive into how blockly itself works. 

There are a number of good first issues available in blockly-samples so that is probably the best place to start. Some of them are more good-first-issues than others, so feel free to look at a few and pick based on your experience level. Some of them tell you step by step exactly what to change and some of them are more open ended. If you want to tackle any of them and get stuck on something, please ask and we'll try to help :)