Skip to content

docs(self-update): Review Vercel config additions #605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dcramer merged 3 commits into from
Jun 15, 2026
+39 −135
Merged

docs(self-update): Review Vercel config additions #605

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d19924e
docs(self-update): Review Vercel config additions
dcramer Jun 15, 2026
0a8f975
docs(self-update): Clarify Vercel fallback review
dcramer Jun 15, 2026
7c2521a
docs(self-update): Compress update workflow
dcramer Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 39 additions & 135 deletions packages/junior-maintenance/skills/self-update/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ git branch --show-current

Stop if `package.json`, `pnpm-lock.yaml`, or `pnpm-workspace.yaml` has unrelated uncommitted changes.

### 2. Inventory deps
### 2. Inventory and target

Collect direct Junior deps from `package.json` — `@sentry/junior` and names starting with `@sentry/junior-`. Record each package's name, current version, and dependency section (`dependencies` / `devDependencies` / `optionalDependencies`). All must be pinned to the same exact version. Do not move packages between sections.
Inventory direct Junior deps from `package.json`: `@sentry/junior` and `@sentry/junior-*`. Record package, current exact version, and dependency section. Keep all Junior deps on one version and do not move packages between sections.

### 3. Resolve target
Resolve the target:

```bash
pnpm view @sentry/junior dist-tags.latest
Expand All @@ -34,36 +34,19 @@ pnpm view <package>@<target> version

Stop if any package lacks the target on npm.

### 3b. Build Junior release context
### 3. Build release context

Junior does not publish GitHub releases, git tags, or a CHANGELOG. Build a best-effort release summary to guide the update and populate the PR body.
Junior does not publish GitHub releases, tags, or a changelog. Use npm publish timestamps to summarize merged PRs between `old_version` and `target_version`:

1. Note `old_version` (current `@sentry/junior` from step 2) and `target_version` (from step 3).

2. Fetch npm publish timestamps:

```bash
pnpm view @sentry/junior time --json
```

Extract `old_published_at` and `target_published_at` from the result.

3. Query merged PRs in `getsentry/junior` between those timestamps:

```bash
gh pr list --repo getsentry/junior --state merged \
--search "merged:>=<old_published_at> merged:<=<target_published_at>" \
--limit 100 \
--json number,title,url,mergedAt
```

4. Classify the results:
- **Breaking:** PR titles matching `^[a-z]+([^)]*)!:` (conventional-commit `!` marker), or body containing `BREAKING CHANGE`.
- **Config-relevant:** titles/scopes mentioning `config`, `plugins`, `nitro`, `createApp`, `runtime`, `credentials`, `egress`, or `example`.

5. Save a compact summary — total PR count, breaking PRs (title + URL), config-relevant PRs — for the PR body. Do not list every fix/chore PR.
```bash
pnpm view @sentry/junior time --json
gh pr list --repo getsentry/junior --state merged \
--search "merged:>=<old_published_at> merged:<=<target_published_at>" \
--limit 100 \
--json number,title,url,mergedAt
```

6. If breaking PRs are found, flag the update as needing manual review in the PR body and keep the PR draft. Do **not** abort the update — proceed and let checks and the config comparison (step 6c) surface concrete issues.
Save total PR count, breaking PRs (`!` or `BREAKING CHANGE`), and config-relevant PRs (`config`, `plugins`, `nitro`, `createApp`, `runtime`, `credentials`, `egress`, `example`). If any breaking PR exists, keep the PR draft and call out manual review, but continue the update.

### 4. Create or reuse branch

Expand All @@ -77,124 +60,55 @@ If `pnpm-workspace.yaml` has a `minimumReleaseAgeExclude` list, ensure every Jun

Group `pnpm add` by dependency section:

| Section | Flag |
|---------|------|
| `dependencies` | `-E` |
| `devDependencies` | `-D -E` |
| `optionalDependencies` | `-O -E` |

```bash
pnpm add -E <deps-packages>@<target> ...
pnpm add -D -E <devDeps-packages>@<target> ... # if any
pnpm add -O -E <optDeps-packages>@<target> ... # if any
pnpm add -D -E <devDeps-packages>@<target> ...
pnpm add -O -E <optDeps-packages>@<target> ...
```

Do not manually edit versions in `package.json`. Do not use local `../junior` linking scripts.

### 6b. Sync `nitro.config.ts` plugin packages

After updating deps, check whether any **new** `@sentry/junior-*` packages were added (i.e. present in the new `package.json` but absent before the update). For each newly added package, ensure it is also listed in the `plugins.packages` array inside `juniorNitro({...})` in `nitro.config.ts`.

**Packages that are NOT standalone plugins and do NOT need a `plugins.packages` entry:**
- `@sentry/junior` (the base runtime)
- `@sentry/junior-plugin-api` (plugin development utilities)
- `@sentry/junior-testing` (test utilities)
### 7. Sync local config

For every other newly added `@sentry/junior-*` package, add it to `nitro.config.ts` if missing:

```typescript
// nitro.config.ts — append the new package to plugins.packages
juniorNitro({
plugins: { packages: [
// ... existing entries ...
"@sentry/junior-<new-package>", // ← add here
] },
})
```

Verify by running:
If a new standalone `@sentry/junior-*` plugin package was added, list it in `juniorNitro({ plugins.packages })`. Exclude the base/runtime utility packages: `@sentry/junior`, `@sentry/junior-plugin-api`, `@sentry/junior-testing`.

```bash
node scripts/check-plugin-packages.mjs
```

This must exit 0 before proceeding. If it fails, fix `nitro.config.ts` and rerun.

### 6c. Compare consumer config against the Junior example app

After updating deps, compare this app's configuration files against `apps/example/` in `getsentry/junior` for the target version. Goal: catch config-shape drift before checks run.

1. Clone `getsentry/junior` into a temp directory (skip if already present from a prior run):
Compare the consumer config with `apps/example` at `target_ref` to catch shape drift. Choose `target_ref` from the version bump commit, then the publish timestamp, then `origin/main` as approximate:

```bash
git clone --filter=blob:none --depth=200 https://github.com/getsentry/junior.git /tmp/junior-upstream
cd /tmp/junior-upstream
```

2. Select the best source ref for `target_version`:

a. Try to find the version-bump commit:
```bash
git log --oneline -S'"version": "<target_version>"' -- packages/junior/package.json
```
If found, check out that commit.

b. If not found, find the commit just before the npm publish timestamp:
```bash
git rev-list -n 1 --before="<target_published_at>" origin/main
```
If found, check out that commit.

c. If neither works, use `origin/main` — mark the comparison as approximate in the PR body.

3. Run focused diffs between example app and consumer app:

```bash
git diff --no-index -- /tmp/junior-upstream/apps/example/nitro.config.ts nitro.config.ts
git diff --no-index -- /tmp/junior-upstream/apps/example/plugins.ts plugins.ts
git diff --no-index -- /tmp/junior-upstream/apps/example/server.ts server.ts
```

4. Interpret the diffs structurally. Look for changes in:
- `juniorNitro()` option shape (new/removed/renamed options)
- `defineJuniorPlugins([...])` usage or call convention
- Plugin factory call signatures (e.g. `githubPlugin({ ... })`)
- `createApp({ ... })` option keys
- Required support devDeps (`nitro`, `jiti`, `typescript`)

**Ignore** app-local differences: env var names, local plugin/skill registrations, custom config defaults, SOUL/WORLD content, Slack personality settings.

5. Apply only obvious, low-risk fixes automatically — e.g. updating a renamed option key or adding a required new argument when the value is inferrable. For everything else, add a PR-body action item.

6. For `package.json`, compare only the build tooling (`nitro`, `jiti`, `typescript`) — do not copy the example's plugin dep list or version pins.

7. Save findings and any actions taken for the PR body.
```bash
git clone --filter=blob:none --depth=200 https://github.com/getsentry/junior.git /tmp/junior-upstream
git -C /tmp/junior-upstream log --oneline -S'"version": "<target_version>"' -- packages/junior/package.json
git -C /tmp/junior-upstream rev-list -n 1 --before="<target_published_at>" origin/main
git -C /tmp/junior-upstream checkout <target_ref>
git diff --no-index -- /tmp/junior-upstream/apps/example/nitro.config.ts nitro.config.ts
git diff --no-index -- /tmp/junior-upstream/apps/example/plugins.ts plugins.ts
git diff --no-index -- /tmp/junior-upstream/apps/example/server.ts server.ts
```

### 7. Verify lockfile correctness
Ignore app-local values. Apply only obvious low-risk fixes; put ambiguous drift in the PR body. For `package.json`, compare only build tooling (`nitro`, `jiti`, `typescript`), not plugin dependency lists or pins.

1. Check changed files:
```bash
git diff --name-only
```
Expected: `package.json`, `pnpm-lock.yaml`, optionally `pnpm-workspace.yaml`, and optionally `nitro.config.ts` if plugin registration changed in step 6b. Flag anything else.
For `vercel.json`, do not normalize the whole file against the example. Use upstream diff-backed changes when possible:

2. Confirm every Junior dep in `package.json` shows exact `<target>` — no old versions remain.
```bash
git -C /tmp/junior-upstream diff <old_ref>..<target_ref> -- apps/example/vercel.json
```

3. Prove lockfile agrees with package.json:
```bash
pnpm install --frozen-lockfile
```
If this fails, repair with `pnpm install --lockfile-only` then rerun. Stop if still broken.
Only act on Junior-owned deployment requirements proven by that diff or by release-window PRs/docs. If `old_ref` is unavailable, target-only example entries are context, not proof; mark the review approximate and leave a manual review item when needed.

### 8. Run checks
### 8. Verify

```bash
git diff --name-only
pnpm install --frozen-lockfile
pnpm check
pnpm typecheck
pnpm build
```

Classify failures: update-related → fix before PR; pre-existing or environment → capture in PR and disclose. Do not silently skip failed checks.
Expected changed files: `package.json`, `pnpm-lock.yaml`, optional `pnpm-workspace.yaml`, optional `nitro.config.ts`, optional `vercel.json`. Confirm every Junior dep is exactly `<target>`. If the frozen install fails, repair with `pnpm install --lockfile-only` and rerun. Fix update-related check failures; disclose pre-existing or environment failures.

### 9. Commit

Expand All @@ -208,22 +122,12 @@ Mention `minimumReleaseAgeExclude` sync if `pnpm-workspace.yaml` changed.

### 10. Push and open/update draft PR

PR body sections (in order):

1. **Version change** — old → new, package list with sections.
2. **Junior release window** — total PR count, breaking PRs (title + URL), config-relevant PRs. Sourced from step 3b. Include the disclaimer: _Junior does not publish GitHub releases, tags, or a changelog. This summary is derived from npm publish timestamps and merged PRs._
3. **Example app config comparison** — source ref used (commit SHA or approximate), files compared, findings, actions taken. Sourced from step 6c.
4. **`minimumReleaseAgeExclude` changes** (if any).
5. **`nitro.config.ts` plugin registration changes** (if any).
6. **Check results** — pass/fail per check, pre-existing failures noted.
7. **Unexpected diffs** — any changed files beyond `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `nitro.config.ts`.

If breaking PRs were found in step 3b, or config comparison found unresolved drift, or checks failed — keep the PR as draft and add a "Manual review required" section at the top summarizing blockers.
Open a draft PR. Include version change, release-window summary with the no-changelog disclaimer, config comparison findings, optional workspace/plugin/vercel changes, check results, and unexpected diffs. Add **Manual review required** when breaking PRs, unresolved config drift, approximate Vercel review, or failed checks exist.

## Stop conditions

- Any Junior package lacks the target version on npm.
- `pnpm install --frozen-lockfile` fails after repair.
- Checks fail for non-pre-existing, non-environment reasons and no safe config fix is available from step 6c.
- Checks fail for non-pre-existing, non-environment reasons and no safe config fix is available from step 7.
- `package.json` changed but `pnpm-lock.yaml` did not.
- Example app comparison reveals a breaking plugin signature change whose required values cannot be inferred from the existing consumer config.
Loading