|
| 1 | +# V1 Release Plan |
| 2 | + |
| 3 | +This plan moves `create-electrobun-stack` from the current pre-1.0 package to a stable `1.0.0` release. |
| 4 | + |
| 5 | +## Current Baseline |
| 6 | + |
| 7 | +- Latest published npm version: `0.1.1`. |
| 8 | +- The package builds to `dist/index.mjs` with `tsdown`. |
| 9 | +- The CLI package includes `dist`, `docs`, and `templates`. |
| 10 | +- CI runs lint, typecheck, tests, build, and package dry-run. |
| 11 | +- Publishing is wired through the GitHub release workflow. |
| 12 | +- Local release gates now include `bun run validate`, `bun run validate:render`, and `bun run pack:smoke`. |
| 13 | +- The default stack is a Bun-powered Electrobun app with React, Vite, Tailwind CSS, TanStack Router, typed RPC, Biome, Bun tests, app menu, local navigation rules, and a `ces.json` manifest. |
| 14 | + |
| 15 | +## V1 Definition |
| 16 | + |
| 17 | +V1 means the CLI can be recommended for new projects without caveats around package install, generated app correctness, or manifest compatibility. |
| 18 | + |
| 19 | +The release is ready when: |
| 20 | + |
| 21 | +- The published CLI works through `npm create`, `npx`, and `bunx --bun`. |
| 22 | +- Existing option categories feel complete enough for V1 without adding new categories just to increase surface area. |
| 23 | +- Every documented stack option is covered by tests or a deliberate manual verification checklist. |
| 24 | +- Generated projects can install dependencies, run development commands, typecheck, lint, test, and build for the supported option matrix. |
| 25 | +- `ces.json` has a stable compatibility story for future `add` operations. |
| 26 | +- The docs match the shipped behavior and explain the supported boundaries clearly. |
| 27 | +- The release process can produce `1.0.0` from a GitHub release without manual package surgery. |
| 28 | + |
| 29 | +## Phase 1: Stabilize The Public Contract |
| 30 | + |
| 31 | +Goal: decide what V1 promises and avoid accidental breaking changes after release. |
| 32 | + |
| 33 | +- Freeze the V1 CLI command shape: |
| 34 | + - `create-electrobun-stack <project>` |
| 35 | + - `create-electrobun-stack add` |
| 36 | + - `--dry-run`, `--yes`, `--cwd`, `--install`, `--git`, and stack flags. |
| 37 | +- Mark the V1-supported stack options in `docs/options.md`. |
| 38 | +- Decide whether `minimal`, `standard`, and `full` should remain aliases for V1 or whether only `minimal` should be advertised. |
| 39 | +- Document the compatibility rules for `ces.json`: |
| 40 | + - V1 manifests are additive. |
| 41 | + - Existing generated apps should keep working with future `add` features. |
| 42 | + - Breaking manifest migrations require a documented migration path. |
| 43 | +- Add a short compatibility policy to `docs/manifest.md`. |
| 44 | + |
| 45 | +Exit criteria: |
| 46 | + |
| 47 | +- Docs clearly say what is supported in V1. |
| 48 | +- Any accepted-but-equivalent template profiles are documented as aliases or hidden from the primary examples. |
| 49 | +- No user-facing flag is left ambiguous. |
| 50 | + |
| 51 | +## Phase 2: Expand Existing Option Categories |
| 52 | + |
| 53 | +Goal: make the stack chooser feel complete before V1 without adding new categories or padding the CLI with weak options. |
| 54 | + |
| 55 | +Use these rules for the V1 option depth pass: |
| 56 | + |
| 57 | +- Add options only inside existing categories. |
| 58 | +- Prefer options with clear generated-file differences over cosmetic aliases. |
| 59 | +- Do not add a choice unless it can install, typecheck, lint, test when applicable, and build. |
| 60 | +- Keep every new option additive through `create-electrobun-stack add` when that makes sense. |
| 61 | +- If a category remains single-choice, document why it is intentionally fixed for V1. |
| 62 | + |
| 63 | +Candidate options to evaluate: |
| 64 | + |
| 65 | +| Category | Current options | V1 candidates | |
| 66 | +| --- | --- | --- | |
| 67 | +| Template | `minimal`, `standard`, `full` aliases | Make `standard` and `full` distinct profiles, or remove them from primary docs until they differ. | |
| 68 | +| Frontend | `react` | Add `preact` or `vue` only if generated Electrobun/Vite projects stay low-maintenance. | |
| 69 | +| Router | `tanstack-router`, `react-router`, `none` | Add a lightweight router option only if it meaningfully differs from `none` and React Router. | |
| 70 | +| Query | `tanstack-query`, `none` | Consider `swr` for a smaller client-side data option. | |
| 71 | +| Styling | `tailwindcss`, `css` | Consider CSS Modules or UnoCSS if the generated app remains simple. | |
| 72 | +| UI | `shadcn`, `none` | Consider a lightweight accessible component starter, but avoid a large design-system commitment before V1. | |
| 73 | +| Auth | `app-lock`, `none` | Add a stronger local PIN/password lock flow if it fits desktop-only auth. | |
| 74 | +| Database | `sqlite`, `none` | Consider an embedded JSON/file-store option if it is meaningfully different from settings storage. | |
| 75 | +| ORM | `drizzle`, `none` | Consider keeping this as-is unless a second ORM has clear Electrobun value. | |
| 76 | +| DB setup | `seed`, `none` | Add migrations/bootstrap options if they work with SQLite and Drizzle. | |
| 77 | +| Settings | `json`, `database`, `none` | Consider encrypted local settings or typed preferences examples. | |
| 78 | +| Package manager | `bun`, `npm`, `pnpm`, `yarn` | Already full enough for V1. | |
| 79 | +| Testing | `bun`, `none` | Add Playwright only if the generated app can run it reliably in CI. | |
| 80 | +| Addons | `turborepo`, `none` | Add editor config, GitHub Actions, or Docker only if each produces concrete generated files. | |
| 81 | +| Examples | `rpc`, `none` | Add settings, database, file-dialog, or routing examples tied to selected options. | |
| 82 | +| API | `electrobun-rpc`, `none` | Consider a static preload/helper option only if it fits Electrobun's model. | |
| 83 | +| App menu | `edit`, `none` | Add app/about or file menu presets. | |
| 84 | +| Build env | `dev`, `canary`, `stable` | Already full enough for V1. | |
| 85 | +| Build targets | `current`, `all` | Consider explicit platform sets only if Electrobun packaging supports them cleanly. | |
| 86 | +| Navigation | `local-only`, `none` | Add external-link-open-in-browser behavior if it is safe by default. | |
| 87 | +| Native utils | `file-dialogs`, `none` | Add clipboard, shell-open, notifications, or path helpers as separate choices if Electrobun supports them cleanly. | |
| 88 | +| Window style | `native`, `hidden-inset` | Add frameless or custom titlebar only if keyboard/window controls remain correct on supported OSes. | |
| 89 | +| Runtime | `bun` | Keep fixed for V1 unless Electrobun supports another runtime; document it as an intentional constraint. | |
| 90 | + |
| 91 | +Recommended V1 minimum: |
| 92 | + |
| 93 | +- Make `standard` and `full` distinct or stop advertising them as real choices. |
| 94 | +- Add at least one substantial option to two sparse categories, with `native-utils`, `examples`, `app-menu`, `settings`, and `testing` as the best first candidates. |
| 95 | +- Document categories that should stay narrow for V1, especially `runtime`, `frontend`, `database`, and `orm` if they remain single-choice. |
| 96 | + |
| 97 | +Exit criteria: |
| 98 | + |
| 99 | +- Every existing category has either multiple useful choices or a documented reason it stays narrow for V1. |
| 100 | +- New option work is represented in `src/options.ts`, templates, manifest/schema docs, CLI docs, generated-project docs, and tests. |
| 101 | +- The full validation matrix includes every new option at least once. |
| 102 | + |
| 103 | +## Phase 3: Prove Generated Projects Work |
| 104 | + |
| 105 | +Goal: test real generated projects, not just renderer template output. |
| 106 | + |
| 107 | +- Add integration tests that scaffold representative projects into temp directories. |
| 108 | +- For each representative project, run: |
| 109 | + - dependency installation with the selected package manager when practical, |
| 110 | + - `bun run typecheck`, |
| 111 | + - `bun run lint`, |
| 112 | + - `bun test` when test scaffolding is enabled, |
| 113 | + - `bun run build`. |
| 114 | +- Cover the default stack as the highest-priority path. |
| 115 | +- Cover at least these option combinations: |
| 116 | + - default stack, |
| 117 | + - `--router react-router --query tanstack-query`, |
| 118 | + - `--router none --styling css --examples none`, |
| 119 | + - `--database sqlite --orm drizzle --settings database`, |
| 120 | + - `--native-utils file-dialogs --window-style hidden-inset`, |
| 121 | + - `--addons turborepo`, |
| 122 | + - `--ui shadcn`. |
| 123 | +- Keep fast unit tests for parser, manifest, and template behavior. |
| 124 | +- Add slower generated-project validation behind a separate script, for example `bun run validate`. |
| 125 | + |
| 126 | +Exit criteria: |
| 127 | + |
| 128 | +- CI runs the fast suite on every PR. |
| 129 | +- A full generated-project validation command exists and passes before release. |
| 130 | +- Failures identify the selected stack combination, generated path, and command that failed. |
| 131 | + |
| 132 | +## Phase 4: Harden Package Publishing |
| 133 | + |
| 134 | +Goal: make npm release boring. |
| 135 | + |
| 136 | +- Confirm `npm pack --dry-run` includes only intended files. |
| 137 | +- Add package smoke tests against the packed tarball: |
| 138 | + - install the tarball into a temp project, |
| 139 | + - run `create-electrobun-stack --version`, |
| 140 | + - scaffold with `--dry-run`, |
| 141 | + - scaffold a real app without dependency install. |
| 142 | +- Decide whether V1 publishes only from GitHub releases or also supports manual `workflow_dispatch`. |
| 143 | +- Ensure `NPM_TOKEN` and provenance settings are configured in GitHub. |
| 144 | +- Add release notes guidance for `0.x -> 1.0.0`. |
| 145 | +- Add a `CHANGELOG.md` before the first release candidate. |
| 146 | + |
| 147 | +Exit criteria: |
| 148 | + |
| 149 | +- A local or CI script proves the packed package works before publish. |
| 150 | +- The publish workflow has been tested with a dry run. |
| 151 | +- Release notes have a repeatable format. |
| 152 | + |
| 153 | +## Phase 5: Documentation Pass |
| 154 | + |
| 155 | +Goal: make the first-run path clear and keep generated project docs accurate. |
| 156 | + |
| 157 | +- Verify root README commands against the packed package. |
| 158 | +- Keep `docs/cli.md` aligned with `parseArgs`. |
| 159 | +- Keep `docs/options.md` aligned with `src/options.ts`. |
| 160 | +- Keep `docs/manifest.md` and `docs/ces.schema.json` aligned with generated manifests. |
| 161 | +- Make `docs/generated-project.md` describe the actual default app lifecycle. |
| 162 | +- Update `docs/llm.txt` after any option or behavior change. |
| 163 | +- Add troubleshooting notes for: |
| 164 | + - Bun version mismatch, |
| 165 | + - Node engine mismatch, |
| 166 | + - Electrobun platform support, |
| 167 | + - package manager install failures, |
| 168 | + - unsupported option combinations. |
| 169 | + |
| 170 | +Exit criteria: |
| 171 | + |
| 172 | +- A new user can follow the README from install to generated app without needing source context. |
| 173 | +- Every public option has one canonical doc location. |
| 174 | +- Generated docs do not mention planned-but-unshipped features as current behavior. |
| 175 | + |
| 176 | +## Phase 6: Release Candidate |
| 177 | + |
| 178 | +Goal: publish a real prerelease and use it like a user. |
| 179 | + |
| 180 | +- Bump to `1.0.0-rc.1`. |
| 181 | +- Publish under an npm prerelease tag, for example `next`. |
| 182 | +- Test the published prerelease with: |
| 183 | + - `npm create electrobun-stack@next my-app`, |
| 184 | + - `npx create-electrobun-stack@next my-app`, |
| 185 | + - `bunx --bun create-electrobun-stack@next my-app`. |
| 186 | +- Generate projects on at least macOS, Linux, and Windows if contributors have access. |
| 187 | +- Track any RC findings as GitHub issues. |
| 188 | +- Avoid new V1 scope unless it fixes correctness, docs, or release confidence. |
| 189 | + |
| 190 | +Exit criteria: |
| 191 | + |
| 192 | +- At least one RC has been published and tested from npm. |
| 193 | +- All release-blocking RC issues are closed. |
| 194 | +- The final V1 diff is limited to version, changelog, docs, or release fixes. |
| 195 | + |
| 196 | +## Phase 7: V1 Release |
| 197 | + |
| 198 | +Goal: ship `1.0.0` with a clear support boundary. |
| 199 | + |
| 200 | +- Bump package version to `1.0.0`. |
| 201 | +- Update manifest examples and schema URLs that include the package version. |
| 202 | +- Update `CHANGELOG.md` with the V1 summary and migration notes. |
| 203 | +- Run the full release gate: |
| 204 | + - `bun install --frozen-lockfile`, |
| 205 | + - `bun run lint`, |
| 206 | + - `bun run typecheck`, |
| 207 | + - `bun test`, |
| 208 | + - `bun run build`, |
| 209 | + - `bun run pack:check`, |
| 210 | + - generated-project validation, |
| 211 | + - packed-package smoke test. |
| 212 | +- Create a GitHub release for `v1.0.0`. |
| 213 | +- Confirm npm shows `1.0.0` as latest. |
| 214 | +- Create a post-release issue list for `1.1.0` improvements. |
| 215 | + |
| 216 | +Exit criteria: |
| 217 | + |
| 218 | +- GitHub release exists for `v1.0.0`. |
| 219 | +- npm `latest` resolves to `1.0.0`. |
| 220 | +- README badges and install commands point at the stable package. |
| 221 | +- Main branch is clean after the release commit and tag. |
| 222 | + |
| 223 | +## Release Blockers |
| 224 | + |
| 225 | +These should block V1: |
| 226 | + |
| 227 | +- Published CLI cannot run through npm, npx, or bunx. |
| 228 | +- Existing option categories still feel like placeholders without an explicit V1 decision. |
| 229 | +- Default generated app cannot install and run its documented commands. |
| 230 | +- `add` corrupts or loses existing `ces.json` state. |
| 231 | +- Documented stack options generate missing imports, missing dependencies, invalid config, or invalid manifests. |
| 232 | +- Package tarball omits required templates, docs, or built entry files. |
| 233 | +- CI or release workflow requires undocumented manual edits. |
| 234 | + |
| 235 | +## Post-V1 Backlog |
| 236 | + |
| 237 | +These are valuable but should not block V1 unless already nearly complete: |
| 238 | + |
| 239 | +- Additional frontend runtimes. |
| 240 | +- Additional databases beyond SQLite. |
| 241 | +- More native Electrobun utilities. |
| 242 | +- End-to-end desktop launch tests. |
| 243 | +- Hosted documentation site. |
0 commit comments