Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (61 loc) · 2.92 KB

CONTRIBUTING.md

File metadata and controls

82 lines (61 loc) · 2.92 KB

Contributing

Thanks for your interest! This is an open-source EmDash plugin. PRs and issues are welcome.

Quick start

git clone https://github.com/drudge/emdash-plugin-postmark
cd emdash-plugin-postmark
pnpm install

# Develop with watch builds
pnpm dev

# Run the test suite
pnpm test

# With coverage (must pass thresholds: 80/75/80/80)
pnpm test:coverage

# Typecheck
pnpm typecheck

# Build
pnpm build

Project layout

src/
├── index.ts          # Descriptor factory (Vite build-time)
├── sandbox-entry.ts  # definePlugin() (request-time)
├── postmark.ts       # Thin REST client over fetch
├── config.ts         # KV + env settings resolver
├── deliver.ts        # email:deliver hook
├── admin.ts          # Block Kit admin handler
├── webhook.ts        # Postmark webhook handler
├── pickers.ts        # Cached live fetchers for streams + signatures
├── logs.ts           # Delivery log storage
├── retry.ts          # withRetry helper
└── constants.ts      # PLUGIN_ID / PLUGIN_VERSION
tests/
├── helpers/mockContext.ts  # In-memory PluginContext mock
└── *.test.ts               # Per-module vitest suites

The descriptor (src/index.ts) and sandbox entry (src/sandbox-entry.ts) are deliberately tiny — they wire imports into the EmDash plugin shape. All real logic lives in src/*.ts modules with their own unit tests.

Coding conventions

  • TypeScript strict mode; noUncheckedIndexedAccess is on. Always handle undefined from array/Map access.
  • No Node built-ins (fs, path, node:crypto, etc.). The plugin must run in Cloudflare Workers / V8 isolates.
  • Use Web APIs (fetch, Web Crypto, URL) for everything platform-related.
  • Comments are reserved for non-obvious why. Code should otherwise be self-explanatory.

Testing

  • Use vitest (pnpm test).
  • Mock the plugin context with tests/helpers/mockContext.ts.
  • All public exports of every src/*.ts module should have at least one test.
  • Coverage thresholds: 80% statements / 80% lines / 80% functions / 75% branches. CI fails below.
  • Avoid touching the network. The Postmark client receives an injected fetch so tests can mock it.

Submitting changes

  1. Open an issue first if the change is non-trivial — it saves churn.
  2. Fork → branch → small focused commits.
  3. pnpm typecheck && pnpm test:coverage must pass.
  4. Update CHANGELOG.md under ## [Unreleased].
  5. Open a PR. Squash-merge unless there's a reason not to.

Releasing

  1. Bump the version in package.json and src/constants.ts (they must match).
  2. Move the ## [Unreleased] entries in CHANGELOG.md under a new dated heading.
  3. Tag the release: git tag vX.Y.Z && git push --tags.
  4. Publish: pnpm publish (CI optionally automates this on tag push — see .github/workflows/).

Code of conduct

Be respectful and constructive. Project discussions are public; please assume good intent.