This document is aimed at developers that have previously forked Blockly and are looking to update to a recent release of Blockly, without patching the library. Although this seems like a daunting task, there are a few steps that you can take to make the process more manageable.
Understand Unforking
Using mainline Blockly means you are using a recently released version of Blockly, and all of your customizations use public Blockly APIs without monkeypatching. Unforking is the work you need to do to implement your fork's custom functionality with mainline APIs.
Simple Unforking Cases
Below are two common reasons you might have forked, and solutions for how to return to mainline:
- You created your own blocks and generators without changing any Blockly code: To unfork in this situation, you can simply move your custom blocks and generators out of the Blockly repository and into your own application's code. You should then be able to then update your Blockly version.
- You added custom functionality on the Blockly namespace without changing any Blockly code: For example, you added custom fields or helper methods only used by your own application. To unfork in this situation, move this custom code to your own application outside of the Blockly repository. You should then be able to then update your Blockly version.
Extensive Unforking Case
Determine forked functionality
The final reason we see users fork is to patch Blockly to create custom functionality that they perceive isn't included upstream at the time. If your fork is significantly out of date, we may have already added the functionality you need, either as plugins or in core. Knowing what features you added in your fork can provide a roadmap for what features you will need to update.
Understand the architecture
Once you understand the features that use fork-specific APIs, consider:
- For each feature using the fork, is there a way to replicate it using Blockly APIs?
- If it seems as though you can't replicate the feature using Blockly APIs, please reach out to us through the forum or file an issue on Github. Our team will then investigate adding APIs to enable your customization.
Determine your unforking path
The next step is to actually begin the process of implementing the new Blockly based architecture for features using the fork. There are two main approaches you can take:
- Upgrade Blockly and see what breaks: You will immediately see the areas in your code that need to be updated. You can use this combined with what you already know is custom behavior to guide your development.
- Refactor your code to separate your features from Blockly: This requires you to gain a deep understanding of which features are custom to your fork and which came from Blockly. Once your code is fully separated, replace your old version of Blockly with the most recent version, then fix any remaining integration issues.
Moving Forward
Here are a few rules that you should follow as a Blockly developer in the future:
- In general, you shouldn't add new classes to the Blockly namespace. You can register custom fields or other registrable classes without declaring them inside of the Blockly repository or on the Blockly namespace.
- You shouldn't rely on Blockly's build tools in order to compile your own application. We don't consider our build tools to be part of the public API, so we may make changes to them which break your application. You are responsible for compiling your application should you wish to do so.
Reach Out
Blockly is always available through the Blockly Forum! If you run into any issues during the unforking process feel free to post them there and we can help.