Contributing

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

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.
• go/ contains the Go v2 module, its direct slack-go/slack block integration, 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

From go/:

go test -race -cover ./...
go vet ./...

All three conformance suites 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 all three 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, TypeScript, and Go API pages are generated during every docs build. Reusable examples live under the matching directory in docs/examples/; tests execute them and compare their output with docs/examples/section_hello.json.

Use LanguageContent with Python, TypeScript, and Go 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.