org.inovus.notifications Private
↗ Repo

# Releasing

How we ship @inovus-medical/notifications to npm.

You do not run npm publish on your laptop. GitHub Actions does it after you merge a Version Packages PR.

Default branch is master. CI and Release only run on pushes to master.

There is also a short note inside the folder itself: .changeset/README.md.

# What is a “changeset”? (human version)

A changeset is a sticky note that says “the npm client changed; bump the version like this and put this line in the changelog.”

It is a markdown file created by a command — not something you write from scratch, and not config.json.

# What’s in the .changeset/ folder

.changeset/
  config.json     ← always present: tool settings (ignore this day-to-day)
  README.md       ← always present: this explanation for humans
  funny-name.md   ← only while a release is pending (the actual “changeset”)
File Purpose
config.json Permanent config (which packages Changesets manages, base branch master, …). Seeing only this after a release is normal.
*.md (except README.md) Pending release notes. Created by pnpm changeset. Removed automatically when Version Packages merges and the version ships.

So: empty of *.md sticky notes ≠ broken. It means nothing is queued for the next npm version.

# What one changeset looks like

After pnpm changeset, you’ll get something like:

---
"@inovus-medical/notifications": patch
---

Fix Retry-After handling in the client.
  • Top: which package + bump size (patch / minor / major)
  • Body: one sentence for CHANGELOG.md

# Day-to-day: publish a new npm version

Do this whenever packages/client (the published package) changes in a way apps should get.

# 1. In your feature PR

pnpm changeset

Follow the prompts:

  1. Select @inovus-medical/notifications
  2. Choose bump:
    • patch — fix / docs / small safe change (0.2.0 → 0.2.1)
    • minor — new feature, backwards compatible
    • major — breaking change
  3. Write a short summary
  4. Commit the new .changeset/*.md file with the rest of the PR

You can have several pending .md files; they fold into one version bump later.

# 2. Merge the PR to master

CI runs (lint, tests, …). Then the Release workflow sees the pending changeset(s) and opens or updates a PR titled something like Version Packages.

That PR:

  • bumps packages/client/package.json version
  • updates packages/client/CHANGELOG.md
  • deletes the consumed .changeset/*.md files (back to just config.json + README)

If GitHub Actions can’t open PRs (org setting), open it yourself: branch changeset-release/master → master. See setup.md §4.2b.

# 3. Merge Version Packages when you want it on npm

That merge runs .github/workflows/release.yml and publishes to npm.

Worker + Supabase deploy from this workflow is paused for now. Re-enable when secrets are set (setup.md §4).

When publish succeeds:

npm view @inovus-medical/notifications version
npm install @inovus-medical/notifications@latest

# Two GitHub Actions (why there are two)

Workflow When Job
CI Every PR and push Lint, typecheck, tests, OpenAPI drift check, build
Release Push to master Create Version Packages PR or publish to npm

Publish lives inside Release → job version-or-publish. Deploy jobs (Supabase / Worker) are currently off.

# Do I need a changeset every time?

What you changed Run pnpm changeset? New npm version?
packages/client (code or package README) Yes After Version Packages merge
Only Worker API / auth / store No No
Only docs under docs/ No No
Only this releasing guide No No

# Worker-only changes

Merging API-only work does not publish npm and (while paused) does not auto-deploy.

To ship the Worker sooner:

  • pnpm --filter @inovus-medical/notifications-api deploy:staging / deploy:production, or
  • Cloudflare Workers Builds, or
  • Re-enable deploy jobs when secrets are ready

# First-time setup (once per repo)

Already done if 0.2.0 (or later) is on npm. Checklist:

  1. npm org @inovus-medical — can publish @inovus-medical/notifications
  2. GitHub secret NPM_TOKEN — Release passes it as both NPM_TOKEN and NODE_AUTH_TOKEN
  3. Allow Actions to open PRs (org + repo) — or open Version Packages manually
  4. Optional later: Cloudflare + Supabase secrets for deploy jobs — setup.md §4

This repo is private, so npm provenance is disabled (not supported for private sources).

# Common questions

“I only see config.json in .changeset/ — where are the markdown files?”
They appear after pnpm changeset and disappear when that release ships. Only config.json (+ this folder’s README) between releases is normal.

“What is config.json?”
Tool configuration. Not a changeset. Don’t delete it.

“Publish fails with E422 … provenance … private.”
Turn provenance off (already done in this repo).

“Publish fails with E404 and my npm token still says Last used: never.”
Release must set NODE_AUTH_TOKEN from secrets.NPM_TOKEN (already in release.yml). Confirm the GitHub secret value is current.

“Release ran but no Version Packages PR.”
Org may block Actions from opening PRs — setup.md §4.2b. Or open changeset-release/master → master yourself.

“I pushed but no Action ran.”
Must be on master.

“I merged to master but nothing on npm.”
No pending changeset, or Version Packages not merged yet, or look at Actions → Release → version-or-publish (not only CI).

“Several .changeset/*.md files — multiple publishes?”
No. One Version Packages merge → one version bump → one publish.

“Can I publish from my laptop?”
Prefer CI. Local is only for emergencies.

“Publish succeeded but deploy failed.”
npm is fine. Deploys are paused anyway; ship the Worker manually if needed.