kill-the-news/CONTRIBUTING.md

Contributing to kill-the-news

Thanks for your interest in contributing! This is a small, self-hosted Cloudflare Worker project. Issues, bug fixes, and well-scoped features are all welcome.

Getting started

Requirements: Node.js (LTS) and npm. A Cloudflare account is only needed to deploy, not to run tests locally.

git clone https://github.com/juherr/kill-the-news.git
cd kill-the-news
npm install          # installs deps and builds client scripts (prepare hook)
npm run dev          # start the local dev server (wrangler dev)

For full setup, deployment, and configuration details, see INSTALL.md.

Development workflow

npm test             # run all tests once
npm run test:watch   # run tests in watch mode
npm run build        # dry-run deploy bundle (wrangler deploy --dry-run)
npm run format       # format with Prettier

Run a single test file:

npx vitest run src/routes/admin.test.ts

Client-side scripts live in src/scripts/client/ and are compiled by esbuild into src/scripts/generated/ (gitignored). They rebuild on npm install; to rebuild manually:

npm run build:client

The architecture, source layout, and KV schema are documented in CLAUDE.md — a good orientation before making changes.

Before opening a pull request

• Add or update tests for any behavior change. Tests live in src/routes/*.test.ts, with shared mocks in src/test/setup.ts.
• Run the checks: npm test, npm run build, and npm run format. Pre-commit hooks (husky + lint-staged) run lint/format on staged files.
• Keep docs in sync. When you change behavior, update the relevant files together:
  • README.md
  • INSTALL.md (setup, deployment, configuration)
  • setup.sh (if setup/deploy assumptions changed)
• Keep PRs focused. One logical change per PR is easier to review.

Commit messages

This project follows Conventional Commits with a scope, matching the existing history. Examples:

feat(admin): collapse create-feed form into accordion
fix(attachments): render inline cid: images in emails and feeds
refactor(home): dedupe byte formatting in storage cards
docs(readme): add Continuous deployment section

Common types: feat, fix, refactor, docs, test, chore.

Releasing

The running version is read from package.json version and inlined at build time (footer, /health, /api/v1/stats). main always carries a -develop pre-release suffix (e.g. 0.3.0-develop) so a dev build is never mistaken for a shipped one — 0.3.0-develop sorts below 0.3.0 per SemVer, meaning "heading toward 0.3.0, not yet released".

The git tag is the source of truth for a release version, not a commit on main. The Release workflow (.github/workflows/release.yml) triggers on a v* tag, strips the -develop suffix in its ephemeral checkout so the published bundle reports the bare X.Y.Z, then builds and creates the GitHub Release. It fails fast if the tag's base doesn't match package.json's base version, which catches tagging the wrong commit. You never commit a bare X.Y.Z to main.

To cut release X.Y.Z (its base must equal main's current X.Y.Z-develop):

git tag vX.Y.Z && git push origin vX.Y.Z   # the workflow aligns + builds + publishes

Then reopen the next cycle on main:

npm version <next>-develop --no-git-tag-version   # e.g. 0.4.0-develop (or 0.3.1-develop for a patch line)
# commit + push

Reporting bugs and requesting features

Open an issue at github.com/juherr/kill-the-news/issues. For bugs, include reproduction steps, expected vs. actual behavior, and your environment (ingestion method, relevant config). For security issues, follow SECURITY.md instead of opening a public issue.

License

By contributing, you agree that your contributions will be licensed under the MIT License.