AGENTS.md · RaspberryPiFoundation/blockly

Sections

1. Project ownership
2. Repository structure
3. Commands
4. Shared configuration
5. Making changes
6. Dependencies
7. Commits and pull requests
8. AI policy
9. Versioning and publishing
10. Code conventions
11. Further reading

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

## Project ownership

Blockly is maintained by the **Raspberry Pi Foundation**.
`RaspberryPiFoundation/blockly` is the canonical upstream. It is **not** a fork of
`google/blockly`, and there is no separate Google-maintained version that this one
tracks or defers to.

Blockly was originally developed at Google, so a lot of legacy remains and it is easy to
conclude otherwise. Two things in particular are not evidence of ownership:

- Most existing files carry a `Copyright <year> Google LLC` header. **Leave them alone.**
  Only new files get the Raspberry Pi Foundation copyright.
- Several hundred links to `developers.google.com/blockly` are still embedded in TSDoc
  and comments. They are stale. Do not add new ones.

When adding a reference or link, use the current locations:

| For               | Use                                                       |
| ----------------- | --------------------------------------------------------- |
| Source repository | `https://github.com/RaspberryPiFoundation/blockly`        |
| Issues            | `https://github.com/RaspberryPiFoundation/blockly/issues` |
| Documentation     | `https://docs.blockly.com`                                |
| Project home      | `https://blockly.com`                                     |

The npm package name is unchanged: the core library is still published as `blockly`.

## Repository structure

This is an npm + Nx monorepo. Workspaces are `packages/*` and `packages/plugins/*`.

| Path                 | Package name   | What it is                                                                      |
| -------------------- | -------------- | ------------------------------------------------------------------------------- |
| `packages/blockly/`  | `blockly`      | The core library                                                                |
| `packages/plugins/*` | `@blockly/*`   | First-party plugins (fields, themes, workspace add-ons) and their build tooling |
| `packages/docs/`     | `blockly-docs` | The Docusaurus developer documentation site                                     |

Detailed guidance lives next to the code it describes. Read the relevant one before working in that area, rather than loading all of them:

- [`packages/blockly/AGENTS.md`](packages/blockly/AGENTS.md) — core library
- [`packages/plugins/AGENTS.md`](packages/plugins/AGENTS.md) — plugins
- [`packages/docs/AGENTS.md`](packages/docs/AGENTS.md) — documentation site

## Commands

Run these from the repo root. Root scripts fan out across workspaces via Nx.

```bash
npm ci                 # Install. Re-run after any pull that changes package-lock.json.

npm run build          # Build every package except the docs site
npm run build-all      # Build everything, including the docs site
npm run build-docs     # Docs site only

npm run test           # Full test suite across all packages. Slow.

npm run lint           # ESLint across all workspaces
npm run lint-fix
npm run format         # Prettier write, whole repo
npm run format-check

npm run clean          # Reset the Nx cache and clean every package
```

To work on a single package, either `cd` into it and use its own scripts, or target it
with Nx from the root. The Nx project name is the package's `name` field, which for
plugins is often not the same as the directory name — run `npx nx show projects` to list
them rather than guessing.

```bash
npx nx show projects
npx nx run blockly:test
npx nx run @blockly/field-slider:test
npx nx run-many -t build --projects=@blockly/field-slider
```

Two things to watch out for:

- `format` and `format-check` exist **only** at the root. Prettier is configured once
  for the whole repo, so there is no per-package equivalent.
- `build`, `test`, `clean`, `lint`, and `start` exist at both levels and mean different
  things. At the root they fan out through Nx; inside a package they run that package's
  own tooling.

## Shared configuration

Tooling is configured once at the root and covers every package. Do not add per-package
copies of these:

- `eslint.config.mjs` — a single flat config with per-package `files` sections
- `.prettierrc.js` — shared base plus `overrides` for core, plugins, and docs, which
  each use different settings
- `nx.json` — target defaults and caching
- `lerna.json` — versioning and publishing
- `commitlint.config.mjs` — conventional commit rules

## Making changes

- **Keep changes minimal and pull requests small.** Change what the task requires and
  nothing else. When you notice unrelated problems along the way, report them rather
  than folding them into the same change.

- **Reach for command line tools before writing tooling.** Most build, migration, and
  inspection tasks are one invocation of `git`, `grep`, `find`, `sed`, or an existing
  `npx` package. Prefer that to a script with its own argument parsing, logging, and
  error handling. A bespoke script is code someone has to maintain; a command is not.
  The same goes for scripts you write for yourself mid-task — prefer the one-liner you
  can throw away.

- **Fix root causes, not symptoms.** Prefer the fix that removes the problem to the one
  that routes around it. Adding a path to `.prettierignore` or an `eslint.config.mjs`
  override, special-casing a single block type, or skipping a failing test are all
  signals that the real issue is still there. Where an exception genuinely is the right
  call, say why in a comment.

- **Leave debugging code alone.** Do not remove or revert `console.log` calls, temporary
  assertions, commented-out experiments, or similar scaffolding that someone else added
  — it is probably load-bearing for whatever they are in the middle of. You can point it
  out, but clean it up only when asked, or when explicitly preparing a final commit or
  pull request.

- **Take a final pass before you finish.** Re-read the whole diff looking for things to
  condense or drop: code that is no longer needed, comments that no longer describe what
  the code does, an abstraction with one caller, your own debugging leftovers.

## Dependencies

`packages/blockly` has **no runtime dependencies**. That is deliberate — it is loaded
into other people's applications — so do not add one.

A new `devDependency` needs a case: what it does, why a few lines of our own code or an
existing dependency is worse, and what it costs in install size and ongoing maintenance.
Weigh that with the author before adding it, not after.

For plugins, `blockly` is always a peer dependency; see
[`packages/plugins/AGENTS.md`](packages/plugins/AGENTS.md).

## Commits and pull requests

Commits follow the conventional commit spec, enforced by commitlint. The type should be
one of `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `refactor`, `release`, `revert`,
or `test`.

Breaking changes must append `!` to the type (for example `feat!:`) **and** be called out
in the pull request description. See [`packages/blockly/AGENTS.md`](packages/blockly/AGENTS.md)
for what counts as a breaking change.

## AI policy

Contributions to Blockly are governed by the
[AI policy](packages/docs/docs/guides/contribute/core/ai_policy.mdx). Read it before
helping with anything that will become a pull request. What it means for you:

- **Do not write pull request descriptions or GitHub comments.** They must be written by
  the human contributor. You may translate text they have written, and you may review a
  draft they have written, but do not draft one or rewrite theirs wholesale. If asked to
  write one, decline, point to the policy, and offer to review their draft instead.
- **Do not work on `good first issue`s.** If the task is an issue with that label, do not
  write code or PR text for it. Those issues exist so new contributors learn Blockly by