Skip to content

development.md

Latest commit

 

History

History
155 lines (118 loc) · 5.85 KB

development.md

File metadata and controls

155 lines (118 loc) · 5.85 KB
Raw

Development and Manual QA

Use the published DevSpace installation for normal work. When testing DevSpace itself, run the source checkout against a checkout-local fork of your DevSpace configuration and SQLite state.

First run in a checkout

Install dependencies, then seed the checkout from your normal DevSpace setup:

pnpm install --frozen-lockfile
pnpm dev:seed
pnpm dev

dev:seed creates an ignored .devspace-dev/ directory in the current checkout. It copies the current config, auth file, DevSpace-local skills and agent profiles, and makes a SQLite backup of the configured state database. The copied config is rewritten so storage.stateDir points at the checkout-local state directory.

pnpm dev only uses that local QA configuration. If the checkout has not been seeded, it stops with an instruction to run pnpm dev:seed instead of silently falling back to your normal DevSpace state.

By default the seed source is ~/.devspace. If your normal installation uses a custom DEVSPACE_CONFIG_DIR, keep that value exported while using dev:seed and dev:reset so both commands fork the same installation.

Testing with ChatGPT

Stop the installed DevSpace server before starting the source checkout so both processes do not compete for the configured port. You can keep the same tunnel and public URL running.

Because the QA database is forked from your normal state, it starts with the same registered OAuth clients and current access and refresh tokens. This usually lets ChatGPT continue through a server restart without setting up a new connection.

The fork is a snapshot, not shared state. OAuth refresh tokens rotate when they are used, so a long-lived QA fork can diverge from the normal installation or from another worktree's older fork. Do not rely on separate QA databases to remain permanently interchangeable without re-authentication.

Switching between worktrees

Each worktree keeps its own .devspace-dev/ state:

# worktree A
pnpm dev:seed
pnpm dev

# stop it, then switch to worktree B
pnpm dev:seed
pnpm dev

Once a worktree has been seeded, later runs only need pnpm dev.

This keeps source changes and persistent QA state isolated without requiring DevSpace to know which Git branch or worktree is active.

Database and migration changes

Do not point experimental source builds at your normal DevSpace state directory. Use the checkout-local fork so migrations operate on disposable data that began as a realistic copy of your current installation.

To repeat a migration from the same baseline, discard the checkout QA state and fork it again:

pnpm dev:reset
pnpm dev

dev:reset replaces the entire .devspace-dev/ directory from the current normal DevSpace config and state. Any QA-only workspace sessions, OAuth changes, agent sessions, and database migrations in that checkout are discarded.

DevSpace also validates the migration journal at startup. If an applied migration version has a different name than the current build expects, or the database contains a migration version unknown to the build, startup fails instead of silently using an incompatible schema.

Normal verification

The usual repository checks remain:

pnpm typecheck
pnpm test
pnpm build

Releases

Releases are published by the manual Release GitHub Actions workflow. Do not publish the package directly from a development checkout for normal releases. The workflow only accepts runs dispatched from main, and the exact commit must already have a successful CI push run.

Prereleases use the beta npm dist-tag. Both beta and release-candidate versions follow the same install channel:

1.1.0-beta.1 -> @beta
1.1.0-beta.2 -> @beta
1.1.0-rc.1   -> @beta
1.1.0        -> @latest

Run the workflow from GitHub Actions and enter the version without a leading v, for example 1.1.0-beta.1. The workflow temporarily writes prerelease versions into package.json, validates and packs that exact source commit, publishes the resulting tarball to npm, and then publishes the matching GitHub release. Prerelease version changes are not committed back to main.

Stable releases use the same temporary version change while building and publishing. After npm and GitHub publication both succeed, the workflow commits the released version back to main as chore(release): prepare vX.Y.Z. If main moved while the release was running, the version sync fails instead of overwriting concurrent work. This keeps the source tree aligned with the latest stable release without creating version commits for every beta or release candidate. A stable release is rejected if its version is lower than either the source version or npm's current latest version.

npm trusted publishing setup

The release workflow authenticates to npm through GitHub Actions OIDC instead of a long-lived npm token. Configure @waishnav/devspace on npm with a GitHub Actions trusted publisher using:

  • repository owner: Waishnav
  • repository: devspace
  • workflow filename: release.yml
  • no GitHub environment
  • allow direct npm publish

The workflow uses a GitHub-hosted runner, requests id-token: write, and pins an npm CLI new enough for trusted publishing. Its package artifact is also attached to a draft GitHub release before npm publication; the GitHub release is made public only after npm succeeds.

Re-running the same version is safe only when it still identifies the same artifact and release channel. Existing npm versions must have the same package integrity as the newly packed tarball and already be assigned to the requested beta or latest dist-tag. Existing draft GitHub releases may be resumed, but public releases are never modified: the workflow verifies npm state and the published GitHub tarball and exits successfully only when they already match. Any partial or mismatched public release fails for manual investigation instead of rewriting published state.