diff --git a/README.md b/README.md index a413fc6c..cb6d1bde 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,42 @@ -# Blockly (Code Studio fork) - -[![npm version](https://img.shields.io/npm/v/@code-dot-org/blockly.svg)](https://www.npmjs.com/package/@code-dot-org/blockly) -[![CircleCI](https://circleci.com/gh/code-dot-org/blockly.svg?style=shield)](https://circleci.com/gh/code-dot-org/blockly) - -This is a fork of [Blockly](https://code.google.com/p/blockly/), an open source visual programming environment. - -Major additions and changes in this fork: - -* Modal editor for function blocks ([function_editor.js](./core/ui/function_editor.js)) -* Scrolling improvements: - * auto-scroll on block drag ([scroll_on_block_drag_handler.js](./core/ui/block_space/scroll_on_block_drag_handler.js)) - * scroll on mouse wheel ([scroll_on_wheel_handler.js](./core/ui/block_space/scroll_on_wheel_handler.js)) -* New in-toolbox trashcan -* Addition of "Functional blocks" and "Contract/Variable Editor" ([contract_editor/](./core/ui/contract_editor/)) for use in the CS in Algebra curriculum - * Blocks have "Block Value Types" ([block_value_type.js](./core/utils/block_value_type.js)) -* Support for "block limits" ([block_limits.js](./core/ui/block_space/block_limits.js)), toolbox blocks which allow only a certain number of instances in the block space -* Support for new block properties ([block.js](./core/ui/block.js)): invisible, un-deletable, immovable, specify-able via a context menu when `Blockly.editBlocks` is set -* Structure: add folders in [core/](./core) to further categorize classes -* New field types: - * Image Dropdown ([field_image_dropdown.js](./core/ui/fields/field_image_dropdown.js)) -* BlockSpace (Workspace) Refactoring: - * moved many static properties and methods from `blockly.js` into a prototype class `BlockSpaceEditor` which can be instantiated multiple times on the same page - * renamed `Workspace` to `BlockSpace` to disambiguate from higher-level `BlockSpaceEditor` - * improved support for multiple blockspaces on a single page -* Playground: add dependency cache and generation script ([tests/update_test_dependencies.sh](./tests/update_test_dependencies.sh)), to allow for testing changes without re-building - * support for [goog.ui.tweak](https://google.github.io/closure-library/source/closure/goog/demos/tweakui.html)s to configure playground page behavior - * debug drawing helpers for block bumping -* Support for a special UI for unattached blocks -* Improvements to block arrangement on initialization -* Testing: add phantomjs-based test runner [test.sh](./test.sh). Tested in CI at root level of this repository. - -## Installation - -1. Download and install JDK version 8 from [here](https://www.oracle.com/technetwork/es/java/javase/downloads/jdk8-downloads-2133151.html) -2. run the following commands: - -``` -cd blockly -npm install -npm run build -``` - -## Usage - -### Playground manual testing page - -There is a playground manual testing page at [tests/playground.html](./tests/playground.html), which requires no build step or server running. - -`open tests/playground.html` - -### Building with apps - -This is the most typical use case for code-dot-org fork development. - -[Apps (aka Code Studio)](https://github.com/code-dot-org/code-dot-org/tree/staging/apps) is a set of blockly apps built on top of blockly, which installs and references this package via NPM. The easiest pathway for local development is to use [npm-link](https://docs.npmjs.com/cli/link): - -``` -cd {blockly repo directory} -npm link -cd {code-dot-org repo directory}/apps -npm link @code-dot-org/blockly -``` - -Apps will now reference your local blockly repository rather than the npm package. If you then make local changes to your repo, you can simply rebuild blockly (via `npm run build` in this repo) and then apps (via `npm run build` in code-dot-org/apps) to communicate those changes to apps. - -### Publishing changes - -To publish a new version to npm switch to the main branch, use `npm login` to sign in as an account with access to the `@code-dot-org` scope, then `npm version [major|minor|patch|premajor|preminor|prepatch]` for the appropriate version bump. This will do the following: - -* Run linting and tests to verify your local repo. -* Rebuild the release package. -* Bump the version, adding a corresponding commit and version tag. -* Push the commit and tag to github. -* Publish the new release package to npm. - -#### Testing changes - -There are a set of utility and integration tests included in `tests/blockly_test.html`, and a playground manual testing page at `tests/playground.html`. - -After adding any new files, you will need to run `./update_test_dependencies.sh` to update the test dependency map, which caches file dependencies so edits can be tested and played with without any re-build time. - -There are three ways the test suites can be run: - -1. `./test.sh` will run the tests in phantomjs -1. To debug failures, you can open the test page in your browser, e.g. `open tests/blockly_test.html` -1. `./deploy.sh` will also run `./test.sh` at the end of its full rebuild. - -##### Other tests covering this package - -[Blockly apps](https://github.com/code-dot-org/code-dot-org/tree/staging/apps) contains many tests that target features of blockly in the context of the code.org curriculum apps. - -Additionally, [Dashboard's UI tests](https://github.com/code-dot-org/code-dot-org/tree/staging/dashboard/test/ui) cover certain features of blockly through Cucumber / Selenium scenarios. +# Blockly (Code Studio fork) - Archived + +This repository historically contained Code.org’s fork of [Blockly](https://blockly.com/), the open-source visual programming environment. The fork existed to support custom features for +Code.org-specific curriculum that were not yet available with mainline Blockly or its plugins. + +## Archival note + +Code.org has fully migrated to mainline Blockly, and this fork is no longer used or published. This repository is archived to preserve historical reference only. It is not maintained, tested, or supported. + +## Major additions and changes in this fork + +- Modal editor for function blocks ([function_editor.js](./core/ui/function_editor.js)) +- Scrolling improvements: + - auto-scroll on block drag ([scroll_on_block_drag_handler.js](./core/ui/block_space/scroll_on_block_drag_handler.js)) + - scroll on mouse wheel ([scroll_on_wheel_handler.js](./core/ui/block_space/scroll_on_wheel_handler.js)) +- New in-toolbox trashcan +- Addition of "Functional blocks" and "Contract/Variable Editor" ([contract_editor/](./core/ui/contract_editor/)) for use in the CS in Algebra curriculum + - Blocks have "Block Value Types" ([block_value_type.js](./core/utils/block_value_type.js)) +- Support for "block limits" ([block_limits.js](./core/ui/block_space/block_limits.js)), toolbox blocks which allow only a certain number of instances in the block space +- Support for new block properties ([block.js](./core/ui/block.js)): invisible, un-deletable, immovable, specify-able via a context menu when `Blockly.editBlocks` is set +- Structure: add folders in [core/](./core) to further categorize classes +- New field types: + - Image Dropdown ([field_image_dropdown.js](./core/ui/fields/field_image_dropdown.js)) +- BlockSpace (Workspace) Refactoring: + - moved many static properties and methods from `blockly.js` into a prototype class `BlockSpaceEditor` which can be instantiated multiple times on the same page + - renamed `Workspace` to `BlockSpace` to disambiguate from higher-level `BlockSpaceEditor` + - improved support for multiple blockspaces on a single page +- Playground: add dependency cache and generation script ([tests/update_test_dependencies.sh](./tests/update_test_dependencies.sh)), to allow for testing changes without re-building + - support for [goog.ui.tweak](https://google.github.io/closure-library/source/closure/goog/demos/tweakui.html)s to configure playground page behavior + - debug drawing helpers for block bumping +- Support for a special UI for unattached blocks +- Improvements to block arrangement on initialization +- Testing: add phantomjs-based test runner [test.sh](./test.sh). Tested in CI at root level of this repository. + +## Current Blockly usage at Code.org + +Code.org no longer uses this repository. Any active development related to Blockly at Code.org should happen against upstream Blockly or within the Code.org repository itself. + +## npm package status + +The `@code-dot-org/blockly` npm package is no longer published or updated. +Do not depend on it for new projects.