Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (51 loc) · 2.8 KB

CONTRIBUTING.md

File metadata and controls

69 lines (51 loc) · 2.8 KB
Raw

Contributing to the Storefront Devkit

This repo grows by adding self-contained assets, never by restructuring. Follow these conventions so the catalog stays coherent and machine-navigable.

The one-asset-per-directory rule

Every template, widget, recipe, or snippet-set lives in its own directory with:

  • README.md — human-facing: what it is, when to use it, how to use it.
  • meta.json — machine-facing metadata (see schema below). manifest.json at the repo root is regenerated by aggregating every meta.json.
  • the asset files themselves.

To add an asset: create the directory, write its README.md + meta.json, add the files, then regenerate the manifest (npm run manifest — or add the entry to manifest.json by hand for now).

meta.json shape

{
  "id": "template-commerce-minimal",
  "kind": "template | widget | recipe | snippet-set | schema | ci | migration | agent-kit",
  "title": "Human title",
  "description": "One or two sentences.",
  "tags": ["commerce", "starter"],
  "contract": "block-palette@3",
  "siteType": "commerce | marketing",
  "requires": { "cli": ">=1.3.0" }
}

id is globally unique and kebab-cased. contract, siteType, and requires are optional but strongly encouraged so consumers can pin compatibility.

Naming

  • Directories and ids: kebab-case.
  • Schema files: <file>.schema.json (e.g. theme.schema.json).
  • Snippet files: <concern>.json named for what they do (hero.json, mega-menu.json, prop65.json), not how they're built.

Versioning & the contract

  • The homepage block contract is versioned as block-palette@N. Assets declare the version they target in meta.json.
  • Breaking a schema → publish a new versioned schema file (e.g. home.v4.schema.json) and leave the prior one in place; existing templates keep validating against their pinned version.
  • Additive changes (new optional field, new block) go into the current schema.
  • Keep a line in CHANGELOG.md for every asset added or contract bump.

The hard boundary (what is NEVER accepted here)

This repo is strictly tenant-side. Do not add:

  • Any reference to platform source paths, build internals, deploy/runner mechanics, or private APIs.
  • Anything that requires reading the platform codebase to understand or use.
  • Any example that weakens the compliance floor (disabling age/ID verification or excise, hiding required warnings, raw HTML/inline JS for regulated tenants).

If an asset can't be understood and used by someone who has only ever seen tenant-owned files and the ToT MCP, it doesn't belong here.

Validation

Every template and snippet must validate against the matching schema in schemas/, and every template must pass tot validate. CI (ci/github-actions/validate.yml) enforces both — run it locally before opening a PR.