microsandbox-rb 0.5.12 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e3bca57a41c8b7a0b03e92baf14dc84f413e89e438616a0ea48c95ea237063
-  data.tar.gz: 4b3498e04b1ea1ff2f03e706bcc401bd9a216f622b38c9bf6e2e33f96a9dfaf9
+  metadata.gz: abfe8d0fedb192bc5efa95a741ae971475a2a5cc441879c092108bc8bdf9eed5
+  data.tar.gz: ffeb9bda17817cc1c58bfe5cc9c7d58543cde155eead9d2e5eb3844c8a48b4dd
 SHA512:
-  metadata.gz: cfed8fb4ae35f54dbb099fb306899c0e669f6ac7a607c283480637125f57575707534607a92604be78b8ca0135b6e1ec15869c369cfb75b809f14a70847f42d7
-  data.tar.gz: 1583a6b01336edb76312cde96b32bca2e124f2f2c815ddb26f5273930fe5e0e40f3b761e44e763a440a0d8ff368ca30cee30ee65991c1518110ad938b23ef6ba
+  metadata.gz: 73379d82644123c717cd7db9391cab9bf72c16b5cf398ea104fb51d2b608353ed9cd6783db55e1490d941ae67728f1c69fe0bd2dcec37c7ad541c56996afea9f
+  data.tar.gz: b20914b13315697e89ec8a72e7620592a9c00d1e8fa908117ef24d64aea9755b431a2298b85d58ed00ca664065f0b626510c7f11fbb919860d3f839c93268a28

data/CHANGELOG.md

@@ -1,11 +1,33 @@
 # Changelog
 
 All notable changes to this gem are documented here. The format is based on
-[Keep a Changelog](https://keepachangelog.com/), and the version tracks the
-upstream microsandbox runtime.
+[Keep a Changelog](https://keepachangelog.com/). The gem follows its own
+[semantic version](https://semver.org/), **independent of** the upstream
+microsandbox runtime it embeds; each release notes the upstream runtime tag it
+wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-23
+
+This release puts the gem on its **own semantic version**, decoupled from the
+upstream microsandbox runtime tag it embeds (which stays at `v0.5.8`). The
+`0.5.x` lineage had stopped tracking upstream 1:1 — gem-only revisions and a
+bundled breaking change (the `0.5.9 → 0.5.10` lifecycle split) had already
+diverged the two numbers. `0.6.0` makes the split explicit; the gem version no
+longer mirrors the upstream tag. See the README's **Versioning** section for the
+gem→runtime map and the go-forward policy. No runtime change and no breaking API
+change in this release.
+
+### Added
+
+- **`Microsandbox.runtime_version`** and the `Microsandbox::RUNTIME_VERSION`
+  constant — report the upstream microsandbox runtime tag this gem build embeds
+  (e.g. `"v0.5.8"`). The gem now versions itself independently of that tag, so
+  this is the supported way to learn which runtime is wrapped.
+  `spec/unit/version_spec.rb` pins the constant to the Cargo git tag so it can't
+  drift.
+
 ## [0.5.12] - 2026-06-23
 
 ### Fixed
@@ -269,6 +291,7 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.8...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.12...v0.6.0
 [0.5.8]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/superradcompany/microsandbox/releases/tag/v0.5.7

data/Cargo.lock

@@ -3249,7 +3249,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.5.12"
+version = "0.6.0"
 dependencies = [
  "chrono",
  "futures",

data/README.md

@@ -374,6 +374,43 @@ Resolution order when no backend is set programmatically: `MSB_BACKEND`
 operations (create/start/stop/remove/get/list, one-shot exec, follow log
 streaming); unsupported operations raise `Microsandbox::UnsupportedError`.
 
+## Versioning
+
+The gem follows its **own** [semantic version](https://semver.org/), **independent
+of** the upstream `microsandbox` runtime it embeds. Early releases (`0.5.7`–`0.5.9`)
+happened to share the upstream tag, but gem-only revisions and a bundled breaking
+change diverged the two numbers — the gem version is **not** a reliable indicator
+of the embedded runtime version. To learn which runtime a build wraps, ask it:
+
+```ruby
+Microsandbox::VERSION          # => "0.6.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.5.8"  (the embedded upstream runtime tag)
+```
+
+| Gem version | Upstream runtime | Notes |
+|-------------|------------------|-------|
+| `0.5.7`  | `v0.5.7` | initial release |
+| `0.5.8`  | `v0.5.7` | gem-only revision |
+| `0.5.9`  | `v0.5.7` | gem-only revision |
+| `0.5.10` | `v0.5.8` | adopts upstream `v0.5.8`; **breaking** lifecycle split |
+| `0.5.11` | `v0.5.8` | gem-only revision |
+| `0.5.12` | `v0.5.8` | gem-only revision |
+| `0.6.0`  | `v0.5.8` | gem version decoupled from the upstream tag; adds `runtime_version` |
+
+**Going forward** — the gem version moves on its own semver track and no longer
+mirrors the upstream tag:
+
+- A **gem-only** change (new bindings, fixes, refactors over the *same* runtime)
+  bumps the gem version by itself.
+- **Adopting a new upstream runtime** bumps the gem version too and updates the
+  pinned git tag, `Microsandbox::RUNTIME_VERSION`, and the table above together.
+- While the gem is `0.x`, a breaking API change bumps the **minor** (`0.5 → 0.6`),
+  not the patch — the `0.5.9 → 0.5.10` lifecycle split predates this policy and is
+  the reason for it.
+
+Every release records its embedded runtime in `CHANGELOG.md`, and
+`Microsandbox.runtime_version` reports it at runtime.
+
 ## Development
 
 ```bash
@@ -406,9 +443,13 @@ or credential setup is needed.
 
 **Each release:**
 
-1. Bump `Microsandbox::VERSION` (and the `tag = "vX.Y.Z"` on the core-crate
-   dependency in `ext/microsandbox/Cargo.toml`) to match the upstream runtime,
-   update `CHANGELOG.md`.
+1. Bump the gem's **own** version — `Microsandbox::VERSION` and the matching
+   `[package] version` in `ext/microsandbox/Cargo.toml` (they must stay equal) —
+   on its independent semver track (see [Versioning](#versioning)); **don't** pick
+   the number to mirror the upstream tag. If the release also adopts a new upstream
+   runtime, bump the `tag = "vX.Y.Z"` on **both** the `microsandbox` and
+   `microsandbox-network` git deps, update `Microsandbox::RUNTIME_VERSION` to match,
+   and add a row to the Versioning table. Update `CHANGELOG.md`.
 2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
    via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required.

data/ext/microsandbox/Cargo.toml

@@ -7,7 +7,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
 # The core-crate dependency below stays pinned at its own tag (v0.5.8).
-version = "0.5.12"
+version = "0.6.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/lib/microsandbox/version.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Gem version. Tracks the upstream microsandbox runtime (currently `v0.5.8`,
-  # the pinned core-crate tag); the patch segment advances for gem-only revisions
-  # that add bindings atop the same core. Must equal the native ext's Cargo crate
-  # version (`Native.version`), enforced by spec/unit/version_spec.rb.
-  VERSION = "0.5.12"
+  # Gem version. Versioned independently of the upstream microsandbox runtime it
+  # embeds: the gem follows its own semver (while 0.x, breaking changes bump the
+  # minor and fixes bump the patch), so the number does NOT track the upstream tag
+  # one-to-one. Consult {RUNTIME_VERSION} for the wrapped runtime, and the
+  # Versioning section of the README for the full gem-to-runtime map. Must equal
+  # the native ext's Cargo crate version (`Native.version`), enforced by
+  # spec/unit/version_spec.rb.
+  VERSION = "0.6.0"
+
+  # The upstream microsandbox runtime release this gem build embeds — the `tag`
+  # pinned on the `microsandbox`/`microsandbox-network` git deps in
+  # ext/microsandbox/Cargo.toml. Exposed at runtime as
+  # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
+  # sync with the Cargo tag so it can't silently drift out of date.
+  RUNTIME_VERSION = "v0.5.8"
 end

data/lib/microsandbox.rb

@@ -45,6 +45,15 @@ module Microsandbox
       VERSION
     end
 
+    # The upstream microsandbox runtime release this gem build embeds (the git
+    # `tag` pinned in ext/microsandbox/Cargo.toml). The gem's own {version} is
+    # versioned independently of this, so consult this to learn which runtime is
+    # wrapped. See the Versioning section of the README for the full map.
+    # @return [String] e.g. "v0.5.8"
+    def runtime_version
+      RUNTIME_VERSION
+    end
+
     # Download and install the `msb` runtime + `libkrunfw` into
     # `~/.microsandbox` (idempotent).
     #

data/sig/microsandbox.rbs

@@ -2,8 +2,10 @@
 
 module Microsandbox
   VERSION: String
+  RUNTIME_VERSION: String
 
   def self.version: () -> String
+  def self.runtime_version: () -> String
   def self.install: () -> nil
   def self.installed?: () -> bool
   def self.ensure_runtime!: () -> nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.12
+  version: 0.6.0
 platform: ruby
 authors:
 - ya-luotao