Skip to main content

contributing

declared-md is an open project. contributions to the spec, CLI, indexer, and docs are welcome.

repositories​

repodescription
declared-md/specnormative specification and JSON schemas
declared-md/validatorCLI for init, validate, preview
declared-md/indexindexer and data files
declared-md/sitedirectory site (Astro)
declared-md/docsthis documentation site

proposing changes to the spec​

the spec is the most important part of the project. changes need careful consideration because they affect validators, indexers, and all existing files.

before opening a PR:

  1. open an issue in declared-md/spec describing the proposed change and the motivation
  2. wait for discussion. spec changes that break existing files require a major version bump.
  3. if accepted, submit a PR with changes to the relevant .md file and schemas/*.schema.json

patch changes (wording, examples): open PR directly.

minor changes (new optional fields): open issue first, then PR.

major changes (breaking required fields): open issue first, gather consensus, then PR.

reporting bugs in the validator​

open an issue in declared-md/validator.

include:

  • the file that produced the unexpected result (or a minimal reproduction)
  • the command you ran
  • the actual output
  • the expected output

code contributions​

  1. fork the relevant repo
  2. create a feature branch
  3. write tests first (vitest for validator and indexer, no specific framework for site)
  4. implement the change
  5. confirm npm test passes and npm run build succeeds
  6. open a PR

versioning​

the spec and CLI share semantic versioning at the spec level:

  • the spec version is in spec/whoami.md, spec/whois.md, spec/whatis.md frontmatter
  • the CLI version in validator/package.json should match the spec version it targets
  • the indexer version in index/package.json is independent

a CLI version of 1.0.x validates against spec 1.0.x. a CLI version of 1.1.0 validates against spec 1.1.0.

architecture reference​

see architecture overview for a full picture of how the components relate.