I’m Maribeth and I’m a software engineer on Blockly.
As you know, Blockly is an open-source project.
One of the great things about open source projects is that anyone can help improve a
project, including you!
In this talk, I’m going to explain why and how you could become a contributor to Blockly.
First, why should you contribute to Blockly?
Open source contributors have many different motivations.
You may want to contribute because you use Blockly in your own application and you want
to fix a bug or add a feature that you’ve been missing.
Or you want to improve Blockly and make other developers’ lives easier.
Maybe you want to learn new skills and deepen your understanding of JavaScript or web development.
Or maybe you are passionate about computer science education and want to add your contribution.
There are lots of reasons to contribute to open source and if any of these appeal to
you, then contributing to Blockly could be a great fit!
Next, we’ll talk about how to get started.
Blockly is written primarily in JavaScript, so you will need some knowledge of JavaScript.
If you don’t know it yet, that’s okay too.
There are other ways to contribute to Blockly besides writing code, and I’ll talk about
those ways at the end of this talk.
Blockly’s development is done on GitHub, so you’ll need to be familiar with the basics
of using git.
If you are new to that, don’t worry!
We have some articles on our developer site that can get you started, and there are many
tutorials online.
Using Git is a skill that will likely come in handy on any programming project.
Throughout the rest of this talk I’ll be assuming some knowledge of GitHub, so you
may want to pause and come back after learning more if you need to.
You might be wondering what kinds of things would be useful for you to contribute.
There are many tasks you could do that would be helpful for the Blockly community!
They fall into two main categories: contributing to core Blockly, and contributing to samples.
Blockly core contains the core library, and blockly-samples contains optional modules,
plugins, examples, and demos.
In both cases, you could modify the existing code to either add a new feature or fix a
bug.
For new features especially, you want to check that it’s something the blockly team has
agreed we actually want to add.
See if there is already an issue on GitHub for the feature, and if not create one there
to start the discussion before starting on the implementation.
For bugs, you can also browse the issues until you find a bug that seems interesting or appropriate
for you to work on.
Some issues may be labelled “good first issue” - those are the issues we think would
be a good introduction to working with the Blockly codebase.
Issues labelled as “help wanted” tend to be issues we think would be nice to have,
but the blockly team itself probably doesn’t have the resources to fix.
Those would be especially high impact to other members of the Blockly community as they may
not happen without you!
You could also consider adding unit tests to either core or a plugin.
There are still areas of the Blockly codebase that don’t have great test coverage, so
adding unit tests helps ensure quality releases in the future.
Adding tests can be a good introduction to the codebase as you need to learn the public
API for a class under test, but you don’t necessarily need to have in-depth knowledge
of how every piece works in order to write a useful test.
Whichever repository you decide to contribute to, you’ll need to fork it, then clone your
fork via git to your own computer.
You’ll work in your own fork of blockly, then make pull requests from your fork to
blockly.
There are a few things to know specifically about contributing to core Blockly.
Blockly core’s main branch is “develop.”
All PRs are made against develop and if you contribute to Blockly, you should make sure
that you’ve branched from develop and opened the PR against develop.
There’s even a checklist in the PR description to help you remember!
Like we talked about earlier, core contains the main library code.
It’s an older codebase; it’s been around since 2011.
That means a lot of the bugs and feature requests we currently have may have existed for a long
time, and the reason they haven’t been resolved is because they are extra tricky or would
require a large refactoring in order to make work.
Those kinds of issues are probably not good choices for your first contribution, but if
you have been using Blockly in your own project and are very familiar with an area of the
code, you can give them a try!
Otherwise, contributing to blockly-samples might be an easier first step.
We talked about contributing via bug fixes or feature requests.
In blockly-samples, you can also contribute entire plugins.
Plugins are modules that extend or add functionality to Blockly.
We have many ideas for plugins that we think would be useful to the Blockly community,
but the team doesn’t have time to work on them all!
Creating a plugin can be a great way to contribute, and it’s easier to get started because you
don’t need to be familiar with how Blockly works under the hood.
Plugins should use only public APIs in Blockly so if you have been using Blockly in your
own project already, you might already have enough experience to create your own plugin.
And if you haven’t, then you can use the various codelabs we have available to learn
about Blockly.
Some plugins can be added to Google’s blockly-samples repository.
These are called first-party plugins and they are plugins that the Blockly team takes responsibility
for publishing and maintaining.
You can also add a third-party plugin, which is one you publish to npm yourself and host
in your own repository for the wider Blockly community to use.
Both types are useful to the community!
If you have an idea for a plugin, you can open an issue on GitHub to see if it’s something
the team would accept as a first-party plugin.
For more information on creating a plugin, you can also check out a video from the 2021
Blockly summit about how to do so.
Creating a codelab is also a way to contribute to Blockly.
If you have learned about a topic in Blockly that you think could be explained better via
hands-on learning, then creating a codelab would be a great way to help other Blockly
developers learn more about that topic.
Codelab content is inside blockly-samples and you can make PRs for that content as usual.
Similarly, samples also contains demos and examples that illustrate how to use a specific
part of Blockly.
Fixing issues here or updating them to current usages is also very helpful to the community,
and these types of issues may be less complex than fixing a bug in the core library itself.
In blockly-samples, branches work a little differently than in core.
While core uses “develop” as the working branch, samples uses “master” directly.
Next, I’ll talk about the setup you need to do in order to make a change in either
Blockly core or Blockly samples.
In addition to GitHub and git, there are other tools we use for Blockly development.
The biggest one is npm.
It stands for node package manager, but it does a lot more these days than just manage
packages.
We use it to manage our dependencies as well as run scripts and continuous integration.
You need to install node, if you don’t already have it.
We recommend using ‘node version manager’, or nvm.
We typically use the “long term support” version of node, and nvm can help you switch
versions easily.
Then you’ll need npm.
Most if not all other dependencies needed can be installed via npm.
Inside of the blockly repository that you downloaded, you can run the command “npm
install” to install all of the dependencies needed to run or develop Blockly.
It’s also a good idea to do this after switching branches or updating your branch if it’s
been a while since the last time you pulled the code, in case the dependencies have changed.
Some tools we use for development are mocha, which runs our unit tests; eslint, which lints
the code; clang-format, which formats the code; and gulp, which assists with various
build and test-related tasks.
Running “npm install” will install all of these tools for you.
For the most part, you don’t need to understand exactly how each of these tools work.
Most of them are part of the validation process, which I’ll talk about next.
Now that you are set up, you can begin making changes to either core or samples.
Let’s say that you fixed a bug you found in core blockly.
What are the steps you should take to submit your fix?
After making any change to blockly, and before submitting it, you should validate your changes.
We do this in a couple of ways: Run your code and make sure that Blockly loads,
there are no errors, and your code behaves as expected.
It’s useful to take screenshots to add to the pull request description so that the reviewer
can understand your change.
Run “npm run start” to start a playground with Blockly so that you can interact with
it.
Format your code to automatically conform to some style guide requirements like indentation
and line length limits.
Run “npm run format” to run clang-format.
Lint your code to make sure it fully adheres to the style guide.
This does some checks that may or may not be automatically fixable by tools.
Run “npm run lint” to run eslint, and make sure there are no errors or new warnings.
Run the automated tests to make sure everything looks good.
Run “npm run test” to run all the tests, including the mocha unit tests, advanced compilation,
and others.
If all of the checks pass, you are ready to open a pull request, or PR.
Make sure you fill out the PR template so that the reviewer can understand your changes
and how they will affect Blockly.
At this stage, our continuous integration will perform some of the same steps as above
so that we can verify that all tests pass.
If you have never contributed to a Google open source project before, you will also
be asked to sign the Contributor Licensing Agreement.
You will need to sign that before your code can be accepted.
If everything looks good with your change, the Blockly team will take care of merging
your PR!
You may be asked to make some changes before your PR is accepted.
If so then you can add those changes to the PR and let the reviewer know it’s ready
for another look.
Other than writing code, there are more ways to contribute as well:
Write documentation for the developer site.
This content isn’t hosted on GitHub, so file an issue and add your suggested content
so that a member of the team can update the relevant page.
Improve our TypeScript definition file.
Those of you using TypeScript may have noticed some areas where our definitions don’t look
quite right.
You could help by fixing those issues either directly in the definition file or in the
underlying JsDoc that generates the definitions, which is preferred.
Answer questions on the forum.
Share your expertise in Blockly with other developers, or dig into an API to help someone
find an answer they need.
File bug reports on core when you notice something is wrong.
Or, help provide reproduction steps when someone else files an issue, so that it’s easier
to find out what’s going wrong and how it might be fixed.
As you can see, there are many ways you can contribute to Blockly.
However you may decide to contribute would be playing a part in improving Blockly for
the entire community, and we hope you’ll consider it!