Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (82 loc) · 8.13 KB

CONTRIBUTING.md

File metadata and controls

107 lines (82 loc) · 8.13 KB
Raw

Contributing

Directory structure:

BlockNote
├── packages/core        - The core of the editor, which includes all logic to get the editor running in vanilla JS.
├── packages/react       - A React wrapper and UI for the editor. Requires additional components for the UI.
├── packages/ariakit     - UI components for the `react` package, made with Ariakit.
├── packages/mantine     - UI components for the `react` package, made with Mantine.
├── packages/shadcn      - UI components for the `react` package, made with Shadcn.
├── packages/server-util - Utilities for converting BlockNote documents into static HTML for server-side rendering.
├── packages/dev-scripts - A set of tools for converting example editor setups into components for the BlockNote website.
├── examples             - Example editor setups used for demos in the BlockNote website and playground.
├── docs                 - Code for the BlockNote website.
├── playground           - A basic page where you can quickly test each of the example editor setups.
└── tests                - Playwright end to end tests.

An introduction into the BlockNote Prosemirror schema can be found in packages/core/src/pm-nodes/README.md.

Running

To run the project, open the command line in the project's root directory and enter the following commands:

# Install all required npm modules
pnpm install

# Start the example project
pnpm dev

Commands

All commands are run from the project root with pnpm, which wraps the vp (vite-plus) task runner. The ones you'll use day to day:

Command Description
pnpm install Install all dependencies.
pnpm dev Start the example editor with live reload.
pnpm start Build the packages, then preview the example editor.
pnpm test Run the unit tests across all packages.
pnpm lint Lint and type-check the codebase. Run this before pushing.
pnpm run check Auto-fix lint and formatting issues across the project.
pnpm build Build all packages.
pnpm e2e Run the Playwright end-to-end tests.

To run the unit tests for a single package, run pnpm test from inside that package's directory; append -u to update snapshots.

Adding packages

  • Add the dependency to the relevant package.json file (packages/xxx/package.json)
  • Double check pnpm-lock.yaml to make sure only the relevant packages have been affected

Packages

Package Size Version
@blocknote/core
@blocknote/react
@blocknote/ariakit
@blocknote/mantine
@blocknote/shadcn
@blocknote/server-util

Releasing

This diagram illustrates the release workflow for the BlockNote monorepo.

Release Workflow

Essentially, when the maintainers have decided to release a new version of BlockNote, they will:

  1. Check that the main branch is in a releasable state:
    • CI status of main branch is green
    • Builds are passing
  2. Bump the package versions using the pnpm run deploy command. This command will:
    1. Based on semantic versioning, determine the next version number.
    2. Apply the new version number to all publishable packages within the monorepo.
    3. Generate a changelog for the new version.
    4. Commit the changes to the main branch.
    5. Create a new git tag for the new version.
    6. Push the changes to the origin remote.
    7. Create a new GitHub Release with the same name as the new version.
    8. Trigger a release workflow.

The release workflow will:

  1. Checkout the main branch.
  2. Install the dependencies.
  3. Build the project.
  4. Login to npm.
  5. Publish the packages to npm.

Publishing a new package

From time to time, you may need to publish a new package to npm. To do this, you cannot just deploy the package to npm, you need to:

  1. Run nx release version --dry-run and check that the version number is correct for the package.
    • Once this is done, you can run nx release version to actually apply the version bump locally (staged to your local git repo).
  2. Run nx release changelog --from <prev-version> <new-version> --dry-run and check that the changelog is correct for the package.
    • Once this is done, you can run the same command without the --dry-run flag to actually apply the changelog, commit & push the changes to the main branch.
  3. The release workflow will automatically publish the package to npm.