Skip to main content

Contributing

slackblocks is a monorepo containing two handwritten implementations and one shared conformance contract. A feature is complete when its wire output and validation category agree in Python and TypeScript.

Repository layout​

  • spec/ contains the normative fixtures, validation cases, limits, and principles.
  • python/ contains the Python package and its tests.
  • typescript/ contains the ESM TypeScript package and its tests.
  • docs/ contains this Docusaurus site and executable examples.

Set up the workspace​

Python development uses uv:

cd python
uv sync --all-groups

JavaScript development uses the pnpm workspace from the repository root:

pnpm install --frozen-lockfile

Run the checks​

From python/:

uv run pytest test/unit test/conformance test/docs
uv run ruff check slackblocks test
uv run mypy slackblocks
uv build --clear
uv run twine check --strict dist/*

From the repository root:

pnpm --filter @nicklambourne/slackblocks typecheck
pnpm --filter @nicklambourne/slackblocks test
pnpm --filter @nicklambourne/slackblocks check:package
pnpm --filter @slackblocks/docs build

The Python and TypeScript conformance suites both exercise every ID in spec/manifest.json. A checked-in conformance/skiplist.txt may document an intentional language gap, but unknown failures and stale skips fail the suite.

Add or change a Block Kit feature​

  1. Add or update canonical JSON in spec/fixtures/valid/, register it in spec/manifest.json, and link the exact official Slack reference used to validate it.
  2. Map every new JSON-producing capability to at least one valid fixture in spec/coverage.json.
  3. Add invalid behavior to spec/fixtures/invalid/manifest.json when the feature introduces a validation rule. Every scalar leaf in spec/limits.json must have a matching invalid case.
  4. Update spec/limits.json for shared scalar constraints.
  5. Implement the feature idiomatically in both packages, or record a reason in the affected skip list.
  6. Add language-native tests and update the relevant guide or executable example.

When introducing a cross-language API, serialized JSON and validation outcomes are shared; public naming and construction style are language-native.

Documentation​

Run the local site from the repository root:

pnpm --filter @slackblocks/docs start

Narrative pages live in docs/docs/. Python and TypeScript API pages are generated during every docs build. Reusable examples live one-per-file under docs/examples/python/ and docs/examples/typescript/; tests execute them and compare their output with docs/examples/section_hello.json.

Use LanguageContent with Python and TypeScript children for language-specific prose or examples. The site-level selector controls which child is shown.

Pull requests​

Keep changes scoped, add a regression test for bug fixes, and include fixture changes whenever wire behavior changes. All local checks relevant to the changed package should pass before review.