Skip to content

docs(release): add release system plan - #39

Merged
codewizdave merged 93 commits into
stagingfrom
docs/release-system-plan
Aug 3, 2026
Merged

docs(release): add release system plan#39
codewizdave merged 93 commits into
stagingfrom
docs/release-system-plan

Conversation

@martyy-code

@martyy-code martyy-code commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a written plan for the release system of @deessejs/errors. The plan is based on a Phase 0 inventory of the current pipeline and replaces the previously undocumented process with a concrete, reviewable spec.

What is in this PR

  • docs/internal/engineering/plans/release-system.md — the plan itself

What is NOT in this PR

  • No code changes
  • No workflow changes
  • No package.json changes
  • No tag or branch changes

The plan documents the current pipeline (Changesets + label version bump on PRs to main + cherry-pick releases from staging) and proposes a clearer rewrite of the GitHub Actions workflow plus a CI lint for changesets on PRs to staging. It also flags accidental drift between CLAUDE.md / CONTRIBUTING.md and the actual workflow.

Open questions

All four open questions are resolved in the document:

  1. Staging long-lived — kept.
  2. Nightlies — out of scope of this plan.
  3. Release engineer — single point of failure accepted for now.
  4. Hotfix path — release/hotfix-<slug> from main.

Next steps

Once this plan is merged into staging, the implementation phases can begin (Phase 0 inventory done, Phase 1 to Phase 6 in the plan body).

Checklist

  • Plan written in English (project convention)
  • No code changes
  • Branch targets staging per the project's release flow
  • Plan references the current workflow (release.yml, .changeset/config.json) truthfully

🤖 Generated with Claude Code

martyy-code and others added 30 commits June 1, 2026 11:59
@martyy-code @claude
chore: release v1.0.0
5548772 
- Update version to 1.0.0
- Add CHANGELOG.md with release notes
- Consume changeset for v1.0.0

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code
Merge branch 'staging'
a378ad7
@martyy-code @claude
ci: configure npm token for changeset publish
59b6367 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
ci: add public access flag for npm publish
7464bcd 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
ci: fix npm access config for changeset publish
e9dd968 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
ci: set changesets access to public
5274291 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
ci: add GitHub Release creation after npm publish
e912632 
Uses softprops/action-gh-release to create release with CHANGELOG notes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
ci: get latest tag for GitHub Release
170bb8a 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
docs: add first draft of documentation site
d11d9a1 
Create initial documentation structure with 13 MDX pages covering:
- Getting started and installation
- Error factory and instance concepts
- Exception chaining with from() and causes()
- Single and multiple inheritance
- Type checking with is()
- Message templates
- API reference
- Practical recipes

Structure managed via meta.json with navigation sections.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code
docs: documentation structure (ready for review)
51a9e00 
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
vercel: add config for monorepo build
dc697e8 
Specify build command, output directory, and install command
to work with Vercel using repo root as root directory.

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
docs: update app name and GitHub repo config
65d125b 
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
docs: apply black theme
c2cceb2 
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
docs: add title to all code blocks
7abaef5 
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
docs: fix code block title syntax
058485a 
Use title="filename" format for code block headers

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@codewizdave
Merge pull request #11 from nesalia-inc/docs/first-draft
545aa42 
docs: first draft of documentation site
@martyy-code
docs: add Vercel Analytics for page views tracking
6b2e341 
Install @vercel/analytics and add Analytics component to layout

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@martyy-code
chore: update pnpm-lock.yaml with new dependency
4e36a59 
🤖 Generated with [Claude Code](https://claude.ai/claude-code)
@codewizdave
Merge pull request #12 from nesalia-inc/docs/vercel-analytics
0263123 
docs: add Vercel Analytics
@martyy-code @claude
docs: add custom favicon
9880078 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat(homepage): create homepage with Flue-inspired design
e2415b8 
- Hero section with blueprint grid background
- Navigation bar with logo and GitHub link
- Code showcase with file header
- Features grid (4 main + 3 secondary + CTA)
- Before/after comparison section
- Install section with npm commands
- Footer with branding
- Uses Inter font (Geist pending Next.js support)
- rounded-none throughout per design system

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix(homepage): use theme CSS variables instead of hardcoded colors
ff1e1a7 
Replace all hardcoded Tailwind colors (gray-950, bg-white, etc.) with
FumaDocs theme CSS variables (bg-fd-primary, text-fd-foreground, etc.)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix(homepage): remove custom header
06a7e19 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat(homepage): add Shiki syntax highlighting
8069d84 
Use shiki for syntax highlighting on code blocks with dual
light/dark theme support (github-light, github-dark).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix(homepage): remove shiki background, use theme bg instead
027448c 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat(homepage): shiki uses theme background, not inline style
94fa763 
Shiki now removes inline background-color from pre element so
it inherits from theme CSS variables (bg-fd-background).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: use bg-background for shiki code blocks
3379ec4 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
refactor(homepage): use new CodeBlock component with terminal style
3884bb6 
- Uses codeToHtml from shiki directly
- Adds terminal-style header with colored dots
- title is optional
- removes old highlight.ts

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: add sizeClasses definition and bg-background
0cbb6fa 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat: add dark mode support for Shiki code blocks
7ee6ae2 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
martyy-code and others added 26 commits June 5, 2026 10:46
@martyy-code @claude
chore: bump version to 1.1.1
4b9bc64 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code
Merge branch 'feat/npm-package-homepage'
2415e10
@martyy-code @claude
feat: add blog system with SEO optimization
f1d4e1d 
- Configure blog collection in source.config.ts
- Create blog listing page with post grid
- Create individual blog post page with Article JSON-LD
- Add share button component
- Create RSS feed at /blog/rss.xml
- Add blog OG images at /og/blog/[slug]
- Update sitemap to include blog routes
- Add RSS link to layout head
- Write first blog post: "Getting Started with @deessejs/errors"
- Install feed package for RSS generation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat: add blog link to navbar
21159f5 
Add Blog link to the navigation bar using Fumadocs links prop
with BookIcon and nested-url active mode.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: filter non-icon links from docs sidebar
6410798 
Only show icon-type links (like GitHub) in the docs sidebar.
Text links like Blog are shown in navbar only.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat: add Docs link to navbar
0cf6bae 
Add Docs link with FileTextIcon alongside Blog link in navbar.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
feat: add external link to deessejs.com in navbar
4c18f7e 
Add ExternalLinkIcon with external indicator for deessejs.com.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: remove external flag from deessejs.com link
c8b3e7e 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: use external flag without type icon for deessejs.com link
a032540 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@martyy-code @claude
fix: update text to DeesseJS
ddce2e0 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@codewizdave
Merge pull request #26 from nesalia-inc/feat/blog-system
64c67bc 
feat: add blog system with SEO optimization
@codewizdave
Update Academy link in footer component
fab0165
@codewizdave
Update footer.tsx
961eb25
@codewizdave
Add 'Home' link to footer component
1397375
@codewizdave
Add Google site verification meta tag
b48b571
@martyy-code @claude
chore: remove Flue framework
e1a3281 
Drop the Flue agent-harness runtime that was wired up for GitHub issue
triage — the project no longer needs a self-hosted agent workflow.

Removed:
- .flue/                  (Hono server + triage workflow)
- flue.config.ts          (Flue build config)
- .github/workflows/issue-triage.yml (CI trigger)
- .agents/skills/triage/  (Flue-backed skill; Claude Code triage skill kept)
- .claude/agents/flue-expert/  (Claude Code agent)
- .claude/agent-memory/flue-expert/  (agent memory)
- temp/flue-triage-plan.md

Deps: dropped @flue/cli, @flue/runtime, hono, valibot (hono and valibot
were only used by the Flue workflow).

Cleanup:
- .claude/skills/triage/SKILL.md: sign-off attribution updated
  from 'Flue Agent + MiniMax M2.7' to 'Tech Lead Agent'.
- DESIGN.md: removed Flue Framework design-inspiration references.

Co-Authored-By: Claude <noreply@anthropic.com>
@codewizdave
Merge pull request #27 from deessejs/chore/remove-flue
be7c31c 
chore: remove Flue framework
@martyy-code @claude
chore: format codebase with prettier 3
e6103ec 
Adds prettier@^3.9.5 as a direct devDep and reformats the project with the
existing .prettierrc config (semi, singleQuote, tabWidth 2, trailingComma es5,
printWidth 100). Adds temp/ to .prettierignore so reference repos and temp
docs are not checked.

This is the natural consequence of adding 'pnpm format:check' to the lint
CI workflow — without a clean baseline the new step would fail on every
PR.

Co-Authored-By: Claude <noreply@anthropic.com>
@martyy-code @claude
chore(deps): bump pnpm to 10.34.5 (CVE-2026-50016)
88cb396 
- Bump packageManager from pnpm@10.30.3 to pnpm@10.34.5 — patches
  CVE-2026-50016 (CVSS 8.8, symlink path-traversal bypassing --ignore-scripts)
- Add prettier@^3.9.5 as a direct devDep (was previously transitive from
  @changesets/cli, locking us to an old 2.8.8)
- Add lint-staged@^17.0.0
- apps/web: add 'lint' script (was previously skipped by turbo lint)
- apps/web: declare eslint + @eslint/js as devDeps (future-proofs against
  shamefully-hoist removal)

Co-Authored-By: Claude <noreply@anthropic.com>
@martyy-code @claude
ci: bump Node 20 -> 22 LTS in all workflows
35ac33b 
- release.yml: enable npm Trusted Publishing (OIDC) via id-token: write
  permission; remove the Configure npm / NPM_TOKEN step. Manual action
  required on npmjs.com before the next release — register a Trusted
  Publisher for workflow release.yml.
- release.yml: limit release trigger to PRs targeting main; tighten 'if'
  to require base.ref == 'main'; checkout main explicitly (was detached
  PR ref, which would have failed on 'git push HEAD').
- lint.yml: add 'pnpm format:check' step.

Co-Authored-By: Claude <noreply@anthropic.com>
@martyy-code @claude
chore(toolchain): use lint-staged in pre-commit
929d862 
- Replace .husky/pre-commit body with 'pnpm exec lint-staged'.
- Drop the legacy '#!/usr/bin/env sh' + '. "$(dirname "$0")/_/husky.sh"'
  shim lines for Husky v10 readiness.
- Add .lintstagedrc.json (eslint --fix + prettier --write on code files;
  prettier --write on docs/config).
- Drop shamefully-hoist=true and legacy-peer-deps=true from .npmrc.
  apps/web (Next.js) builds verified clean without them.
- Extend .prettierignore with temp/.

Known follow-up: lint-staged config needs per-workspace eslint invocations
or a root eslint.config.js (currently fails for some file types because
ESLint 9 flat-config requires the config in the cwd). Tracked separately.

Co-Authored-By: Claude <noreply@anthropic.com>
@martyy-code @claude
fix(web): declare zod as direct dep of apps/web
65a4264 
CI fail fix. The apps/web source.config.ts (and the generated .source/source.config.mjs
loaded by 'next typegen') imports 'zod' directly, but zod was previously
only resolvable via shamefully-hoist=true, which made pnpm hoist transitive
deps to the root node_modules.

Removing shamefully-hoist=true (commit 929d862) exposed this hidden dep:
on a fresh install (CI), pnpm's strict isolation hides zod from apps/web
because it's only declared as a transitive dep of fumadocs-mdx.

Local 'pnpm install' had succeeded because the local node_modules already
contained hoisted zod from the pre-Tier 2 state.

Add zod@^4.4.3 to apps/web's dependencies to make the import explicit.

Co-Authored-By: Claude <noreply@anthropic.com>
@martyy-code @claude
fix(ci): declare shiki as direct dep + extend .prettierignore
57befc6 
Two follow-up issues surfaced by CI on the Tier 1+2 hardening PR:

1. apps/web/src/components/code-block.tsx imports 'shiki' directly, but
   shiki was only resolvable via shamefully-hoist=true (Tier 2 #17 removed
   that flag). Same pattern as the earlier zod fix (commit 65a4264).
   Add shiki@^4.3.1 as an explicit dep of apps/web.

2. pnpm format:check in CI was failing on:
   - .claude/** (agent tooling metadata, not project source)
   - apps/web/.source/** (generated by fumadocs-mdx)
   - apps/web/next-env.d.ts (generated by Next.js)
   - docs/learnings/** (internal learning docs, formatted manually)
   Extend .prettierignore to exclude these paths.

Co-Authored-By: Claude <noreply@anthropic.com>
@codewizdave
Merge pull request #28 from deessejs/chore/tier1-tier2-toolchain-hard…
569c96d 
…ening

chore: Tier 1+2 toolchain hardening (CVE-2026-50016, Node 22, lint-staged, Trusted Publishing)
@martyy-code
docs(release): add release system plan
93a09a8 
Proposes a documented release system plan for @deessejs/errors. The plan
is grounded in a Phase 0 inventory of the current pipeline (Changesets +
'version bump' label + cherry-pick PRs from staging to main) and lists
six implementation phases to harden the workflow.

No code, no workflow changes, no tag changes in this commit.
@martyy-code
style(release): apply prettier formatting to release system plan
2ee356c
@codewizdave
codewizdave merged commit acacf12 into staging Aug 3, 2026
4 checks passed
This was referenced Aug 3, 2026
Merged
Merged
martyy-code added a commit that referenced this pull request Aug 4, 2026
@martyy-code
docs(engineering): add process docs (dev, release, PR authoring) and …
901fd85 
…stacked-PR learnings

Three process docs under docs/internal/engineering/process/, each
tuned to a persona:

- implementing-an-issue.md  — dev's playbook (read issue, branch, code,
  changesets, push, PR). Companion for anyone picking up an issue.
- releasing-a-new-version.md — release engineer's playbook (build the
  release branch, cherry-pick, push, watch the workflow, verify
  artifacts). Mirrors the conventions we hardened in PRs #39-47.
- pr-authoring.md           — standards for the body of a PR (six
  canonical sections, mandatory code sample when public API
  changes, before/after default, after-only when purely additive).
  Enforces what PR #50 demonstrated: documented the .addNote()
  worked-example as the in-doc template.

Also adds docs/learnings/github/stacked-pr/README.md, notes captured
during PR #39-43 setup around how stacked PRs work in GitHub and how
they apply to a release branch.

No code, no workflow changes. Documentation only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@martyy-code @codewizdave