Repository navigation
Conversation
…upgrade` Apps no longer clone the repository. The `northstack` crate is the only thing an app depends on, pinned to an exact version, and it carries everything that isn't the app's: the server library, the TypeScript runtime, the scripts behind `just`, and the guide. - New `northstack` CLI (src/cli.rs): new, check, dev, logs, e2e, new-feature, remove-example, upgrade and the database commands. The dev scripts moved into the crate and run through it. - `northstack new <dir>` copies the example app from the repository at the version's tag (or a local checkout with --local), pins the version, writes AGENTS.md, README.md and docs/northstack.md, and makes the first commit. - Apps run the CLI at their pinned version through a one-line `cli/` crate; the justfile calls it. A global binary of another version refuses to run in the app. - `just upgrade [version]` moves the pin, replaces the guide, prints the changelog's upgrade steps for every skipped version, and runs check. - The guide moved from the README to crates/northstack/GUIDE.md. scripts/guide_test.py replaces readme-test: it creates an app with `northstack new --local`, removes the example and runs the walkthrough. - Release workflow: a `v<version>` tag checks the version and changelog, runs CI, publishes to crates.io with trusted publishing and creates the GitHub release. - Fixes found while testing: .env is created from .env.example when missing, web/dist exists before the first compile, the dev and e2e scripts respect CARGO_TARGET_DIR, and `just dev` no longer prints an error on its first start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A release is now something an agent does from a prompt, with guardrails: - scripts/release.py <patch|minor|major>: from a clean, up-to-date main, turns `## Unreleased` into the version's changelog section, bumps the crate version and opens the "Release v<version>" PR. It refuses an empty Unreleased and a patch release that has upgrade steps. - release.yml now runs on pushes to main: when the crate version has a changelog section but no tag, it runs ci.yml and framework.yml, tags the commit, publishes to crates.io (trusted publishing, or a CARGO_REGISTRY_TOKEN secret until that is set up) and creates the GitHub release. Every step is skipped when already done, so a re-run finishes a failed release. - scripts/changelog_check.py (framework.yml, on PRs): changes that reach apps (the crate, or template files apps keep) add a line under Unreleased; released sections never change; new version sections only come with a version bump. The label `no changelog` skips the first rule. - AGENTS.md: the PR flow (branch, verify, PR, wait for CI, merge), the changelog rules, and the release steps an agent follows. The app template's AGENTS.md gets the same shipping rules. - `just upgrade` ignores the Unreleased section. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CI failed in `just e2e`: the CLI now creates .env when it's missing, and check.sh sourced it, overriding CI's DATABASE_URL, so `just ci` migrated data/dev.db and e2e compiled against a data/ci.db that didn't exist. The CLI already loads .env without overriding set variables, so the scripts no longer source it. Simpler releases for the first version: - release.yml: one plan check (version has notes, no tag yet), the checks, `cargo publish` (skipped if that version is already on crates.io), then `gh release create`, which also makes the tag. Publishing uses the CARGO_REGISTRY_TOKEN secret only. - changelog_check.py: one rule, app-facing changes must touch the changelog. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agents now work on main and push to it; there are no pull requests. - release.py commits "Release v<version>" on main and pushes it; that push starts the release workflow. - The changelog check runs on pushes to main (against the previous commit) and before pushing; `[no changelog]` in a commit message skips it for pure refactors. - AGENTS.md (repo and app template): pull, change, run the checks, push to main, watch CI and fix right away if it goes red. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The changelog check runs on pull requests too, and AGENTS.md (repo and app template) describes both: push to main by default, a PR when the human asks for one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mentioning the marker in a sentence no longer skips the check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Apps no longer clone this repository. They depend on one thing, the
northstackcrate pinned to an exact version, and update withjust upgrade, likecreate-next-appand bumpingnext.How it works
web/northstack/byjust check, as before), the scripts behindjust(moved fromscripts/intosrc/scripts/), the guide and the changelog. No npm package: one version, nothing to keep in step.northstack new <dir>copies the example app from this repo at the version's tag (--local <checkout>for framework work), pinsnorthstack = "=<version>", writes the app'sAGENTS.md,README.mdanddocs/northstack.md(the guide), and makes the first commit.cli/crate; thejustfilecallscargo run -q -p cli -- <command>. A globalnorthstackof another version refuses to run inside the app.just upgrade [version]refuses on uncommitted changes, moves the pin, replacesdocs/northstack.md, prints the changelog's Upgrade steps for every version it skips, then runsjust checkin the new version.crates/northstack/GUIDE.md. The README now has Try it, Updating and Working on northstack sections; the repo'sAGENTS.mdis for framework work, apps get their own.Releases and shipping: agent-run
Agents pull, change, run the checks locally, and push to
main(or open a PR when you ask for one), then watch CI and fix right away if it goes red (AGENTS.md, repo and app template).You prompt "release"; the agent runs
python3 scripts/release.py <patch|minor|major>. It turns## Unreleasedinto the version's changelog section, bumps the crate version, commitsRelease v<version>and pushes tomain. It refuses an empty Unreleased, a patch release that has upgrade steps, a dirty tree, or amainthat differs fromorigin/main.release.ymlruns on every push tomain: when the crate version has a changelog section but no tag, it runsci.ymlandframework.yml, publishes to crates.io (skipped if already there, so a re-run finishes a failed release), then creates the tag and GitHub release. Merging this PR doesn't release anything: the changelog only hasUnreleased.Guardrails:
mainand PRs): changes that reach apps (the crate, or template files apps keep, like theDockerfileorjustfile) must add a line under## Unreleasedwith**Upgrade:**steps for app agents.[no changelog]in the commit message skips it for pure refactors.main, move av*tag, runcargo publishby hand, or push with a failing local check.One-time human step: create a crates.io API token (scopes
publish-new,publish-update) and rungh secret set CARGO_REGISTRY_TOKEN --repo elitan/northstack. Agents are told never to handle the token.Testing
Repo:
just verify,just e2e,cargo publish -p northstack --dry-run, Docker build and run.scripts/guide_test.py(newframework.ymlworkflow):northstack new --localgives an app that passesjust check,just remove-exampleworks, and the guide's feature walkthrough runs as written, ending withjust verify.A fresh app:
just cion an empty database (no file changes),just devstarted from a subfolder,just e2e(4 passed).Upgrade, simulated with a local copy of the crate as a fake 0.2.0 on crates.io: pin and lock updated, guide replaced, TypeScript runtime regenerated, notes printed, check passed; the old binary then refuses to run in the app.
Release tooling:
release.pyin a throwaway clone with a fake origin (first release pushed to main, empty Unreleased, patch refused with upgrade steps, minor, patch after a release, dirty tree, wrong branch, unpushed commits);changelog_check.pypass/fail/[no changelog]cases; the release plan step for unreleased, tagged and new versions.Not run: the release workflow on GitHub (needs a release PR merged), and
just upgrade's crates.io lookup (nothing published yet).CI's sequence (
just ciondata/ci.db, thenjust e2e) in a fresh clone; this caught a bug where the new.envauto-creation overrode CI'sDATABASE_URL.Fixes found while testing:
.envis created from.env.examplewhen missing (sojust checkworks in a fresh clone),web/distexists before the first compile, the dev and e2e scripts respectCARGO_TARGET_DIR, andjust devno longer prints an error on its first start.🤖 Generated with Claude Code