|
|
|
|
@@ -14,8 +14,8 @@ All of these carry the same version and are bumped together:
|
|
|
|
|
|
|
|
|
|
- Every crate in the Cargo workspace (via `version.workspace = true`)
|
|
|
|
|
- The dashboard's `package.json`
|
|
|
|
|
- Docker image tags (`picloud:0.2.0`)
|
|
|
|
|
- Git tags (`v0.2.0`)
|
|
|
|
|
- Docker image tags (`picloud:1.1.0`)
|
|
|
|
|
- Git tags (`v1.1.0`)
|
|
|
|
|
|
|
|
|
|
Defined once in [`Cargo.toml`](../Cargo.toml) under `[workspace.package]`. There is no scenario where one crate is at a different version than another in the same build.
|
|
|
|
|
|
|
|
|
|
@@ -106,19 +106,15 @@ A versioning scheme without enforcement decays in months. Five cheap mechanical
|
|
|
|
|
|
|
|
|
|
## When to bump what
|
|
|
|
|
|
|
|
|
|
The product version follows SemVer applied pragmatically — we're pre-1.0, so the rules are looser:
|
|
|
|
|
The product version uses SemVer with one carve-out for the platform's expansion cadence:
|
|
|
|
|
|
|
|
|
|
- **Patch** (`0.2.0 → 0.2.1`) — bug fixes, no surface change
|
|
|
|
|
- **Minor** (`0.2 → 0.3`) — any surface bump, new features, or breaking changes (pre-1.0 license)
|
|
|
|
|
- **Major** (`0 → 1`) — first stable release; SDK and API both committed to long-term compatibility
|
|
|
|
|
- **Major** (`1.x → 2.0`) — surface major bump on a user-facing contract: removed/renamed/retyped SDK function, retired API version, breaking schema change that requires user action, breaking wire-protocol change.
|
|
|
|
|
- **Minor** (`1.1 → 1.2`) — phase milestone or coherent capability cluster. Bumped when the maintainer marks a release as "the platform moved forward in a way that warrants a number". Typically aligned with blueprint Phase boundaries (Phase 5 → v1.2, Phase 6 → v1.3+).
|
|
|
|
|
- **Patch** (`1.1.0 → 1.1.1`) — everything else: bug fixes AND **additive-only surface changes**. New SDK function, new admin endpoint, new schema migration that only adds tables/columns, new env var, new trigger kind — all patch.
|
|
|
|
|
|
|
|
|
|
After `1.0`, the product version follows strict SemVer based on the *worst* surface change:
|
|
|
|
|
**Why the carve-out:** PiCloud ships in many small additive PRs (every v1.1.x release adds SDK surface). A strict "minor product bump per minor surface bump" rule would inflate the product version faster than the actual user-perceived "platform changed" milestones warrant. Patch-for-additions keeps the minor digit aligned with capability clusters, not individual feature drops.
|
|
|
|
|
|
|
|
|
|
- Any surface major bump → product major bump
|
|
|
|
|
- Any surface minor bump → product minor bump (at minimum)
|
|
|
|
|
- No surface changes → product patch
|
|
|
|
|
|
|
|
|
|
A surface can hit its own `1.0` independently of the product. The SDK in particular is likely to stabilize before the platform does, since scripts in production demand it.
|
|
|
|
|
**Surface versions follow their own rules** (table above) and don't track the product version. A surface can independently hit its own `1.0` or `2.0`. The SDK in particular is likely to stabilize before the platform does, since scripts in production demand it.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
@@ -126,7 +122,7 @@ A surface can hit its own `1.0` independently of the product. The SDK in particu
|
|
|
|
|
|
|
|
|
|
| | Version |
|
|
|
|
|
|---|---|
|
|
|
|
|
| Product | `0.6.0` |
|
|
|
|
|
| Product | `1.1.0` |
|
|
|
|
|
| SDK | `1.1` (adds `ctx.request.params`, `ctx.request.query`, `ctx.request.rest`) |
|
|
|
|
|
| API | `1` (additive: `Script.app_id`, `Route.app_id`, `ExecutionLog.app_id`, new `/api/v1/admin/apps/*` and `/api/v1/admin/api-keys/*` endpoints, `?app=` filter on script list, `Authorization: Bearer pic_…` credential type, 403 responses on previously-401-only admin endpoints when the caller lacks the required capability) |
|
|
|
|
|
| Schema | `6` (matches `migrations/0006_users_authz.sql`) |
|
|
|
|
|
@@ -138,15 +134,19 @@ Read live from `GET /version` on any running instance.
|
|
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
**Adding a `kv.*` SDK in v1.1+:**
|
|
|
|
|
- Workspace bump: `0.2.0 → 0.3.0` (pre-1.0 minor)
|
|
|
|
|
- SDK bump: `"1.0" → "1.1"` (added functions only)
|
|
|
|
|
- API bump: none (no new endpoints affect existing API contract)
|
|
|
|
|
- Schema bump: `1 → 2` (`0002_kv_store.sql` adds the `kv_store` table)
|
|
|
|
|
**Adding a `kv.*` SDK in v1.1.1:**
|
|
|
|
|
- Workspace bump: `1.1.0 → 1.1.1` (patch — additive SDK + schema, no breakage)
|
|
|
|
|
- SDK bump: `"1.1" → "1.2"` (added functions only)
|
|
|
|
|
- API bump: none (admin endpoints for trigger CRUD are additive)
|
|
|
|
|
- Schema bump: `6 → 7` (`0007_kv_store.sql` adds the `kv_store` table)
|
|
|
|
|
|
|
|
|
|
**Cutting the v1.2 release (Phase 5: workflows, advanced query, interceptors):**
|
|
|
|
|
- Workspace bump: `1.1.8 → 1.2.0` (minor — phase milestone)
|
|
|
|
|
- Even if no individual change is breaking, the maintainer-marked phase transition warrants the minor digit.
|
|
|
|
|
|
|
|
|
|
**Renaming `ctx.execution_id` to `ctx.exec_id`:**
|
|
|
|
|
- SDK bump: `"1.x" → "2.0"` (breaking)
|
|
|
|
|
- Product: minor bump pre-1.0, major bump post-1.0
|
|
|
|
|
- SDK bump: `"1.x" → "2.0"` (breaking — removed/retyped script-visible field)
|
|
|
|
|
- Workspace bump: `1.x.y → 2.0.0` (product major — user-facing contract break)
|
|
|
|
|
- Migration path: keep `ctx.execution_id` available in 1.x for a deprecation window, add `ctx.exec_id` alongside; flip to 2.0 only when both fields have shipped together for a release.
|
|
|
|
|
|
|
|
|
|
**Adding pagination to `GET /api/v1/admin/scripts`:**
|
|
|
|
|
|
