Skip to main content

Contributing

Contribution work should preserve a clean boundary between package behavior and examples.

Keep Sample PRs Separate​

Sample PRs may change:

  • sample/**
  • docs/**
  • website/docs/**
  • CI and release scripts that validate samples
  • README links that point to samples

Sample PRs must not include packages/asyncapi/** changes. If a sample reveals a library bug, pause the sample branch and fix the package separately.

Stash And Fix Workflow​

  1. Stash the sample work:

    git stash push -u -m "sample work before library fix"

  2. Create a library-fix branch from main.

  3. Add the package fix and a regression test.

  4. Open and merge the package fix PR.

  5. Return to the sample branch and restore the sample work:

    git stash pop

  6. Confirm the sample PR has no package changes:

    git diff --name-only main...HEAD -- packages/asyncapi
    git diff --cached --name-only -- packages/asyncapi

Both commands should print nothing for a sample-only PR.

Quality Gate​

Run the full gate before opening a PR:

npm run ci

This covers typecheck, 100% coverage, cognitive complexity, release checks, the docs-site build, the security audit, and the sample matrix. Every generated sample document must pass @asyncapi/parser.

Why This Matters​

Samples are documentation, validation, and onboarding material. Package changes alter the public library contract. Keeping them separate makes each PR easier to review, easier to revert, and safer to release.