specwrk 0.19.3 → 0.19.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2eb07bead54ad609b2d8fb821793a60b783485326daeccc092c14343ae96dc0
-  data.tar.gz: c41e008f026a61f2748cc8f5cd9c7dc2c257103518aa89fded4c84c9bd2ca976
+  metadata.gz: ed4bee81f0d4eef75556d4987bfa36101083bd1ee124770857f76ea2827ad036
+  data.tar.gz: e33ddadc340adf10fc4d66bd36598ad3322b27e5cb37dd9e0f32c0d74c65c305
 SHA512:
-  metadata.gz: 1f9a7206df73023a2262d9775ff3b1983f403b4630ce54a04f7c4500ab77c51d30df6262604332b37e37fdf21cb98fe39952fcd0287f8b9ded7811a39ac97afe
-  data.tar.gz: ffbf1b2583044b4f3e4bdbc7cadb35278f93eb64274905c5869398f5ece9d2854ddad0c75463ac8172d025d8dcc7a92c8486d5d9ef581ad269c875aca5c22420
+  metadata.gz: 2ce4eeb7ca55eae597425b10eb3a1236ae8b04fa6bae13f3564d761a88eb138671c1ffae85cf89f7944fb64c463f9ff96b261e9b650df3dbf34675237d91df7d
+  data.tar.gz: 81b3f08f0870b9d7af23476ad2282793e2891c42fa110d18e5f5ae1b567c843eaa945b125fc16d4af72a1b124f5f3e8d5bd214bd8e7804222f6f7c6a1d613649

data/CHANGELOG.md

@@ -1,7 +1,12 @@
 # Changelog
 
 ## Unreleased  
-[Compare](https://github.com/danielwestendorf/specwrk/compare/v0.19.3...main)  
+[Compare](https://github.com/danielwestendorf/specwrk/compare/v0.19.4...main)  
+
+## v0.19.4 — 2026-08-23  
+[Compare](https://github.com/danielwestendorf/specwrk/compare/v0.19.3...v0.19.4)  
+- Return HTTP 423 on lock contention and retry clients with jitter — [#189](https://github.com/danielwestendorf/specwrk/pull/189) by [@danielwestendorf](https://github.com/danielwestendorf)  
+- Document the gem and Docker release process — [#190](https://github.com/danielwestendorf/specwrk/pull/190) by [@danielwestendorf](https://github.com/danielwestendorf)  
 
 ## v0.19.3 — 2026-07-26  
 [Compare](https://github.com/danielwestendorf/specwrk/compare/v0.19.2...v0.19.3)  

data/README.md

@@ -292,6 +292,8 @@ specwrk is different because it:
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/danielwestendorf/specwrk.
 
+Maintainers can follow [RELEASING.md](RELEASING.md) to publish the gem and Docker image.
+
 ## License
 
 The gem is available as open source under the terms of the [LGPLv3 License](http://www.gnu.org/licenses/lgpl-3.0.html).

data/RELEASING.md

@@ -0,0 +1,126 @@
+# Releasing Specwrk
+
+Releases are cut from `main` in two stages:
+
+1. `gem bump` updates the version and creates the release commit.
+2. Bundler's `rake release` task tags the commit, pushes Git, and publishes the gem.
+
+The Docker image is published separately after the gem release.
+
+## One-time setup
+
+Install `gem-release`, which provides the `gem bump` command. It is intentionally
+not a development dependency because it is only needed by maintainers cutting a
+release.
+
+```sh
+gem install gem-release
+```
+
+Configure credentials for RubyGems and Docker Hub:
+
+```sh
+gem signin
+docker login docker.io
+```
+
+The Docker release also requires a buildx builder capable of building `linux/arm64`
+and `linux/amd64` images. Check the active builder with:
+
+```sh
+docker buildx inspect --bootstrap
+```
+
+## Cut the gem release
+
+Start from an up-to-date, clean `main` branch. This is important because
+`rake release` pushes the current branch.
+
+```sh
+git switch main
+git pull --ff-only origin main
+git status --short
+```
+
+Bump the version without committing. Use `patch`, `minor`, `major`, or an
+explicit version number:
+
+```sh
+gem bump --version patch --no-commit
+```
+
+This updates `lib/specwrk/version.rb` while leaving the release changes
+uncommitted. Update `CHANGELOG.md` using the new version:
+
+1. Change the Unreleased comparison link to start at the new version.
+2. Add a dated section for the new version.
+3. Move the Unreleased entries into that section.
+
+Stage the version, changelog, and any release documentation, then create the
+version commit:
+
+```sh
+git add lib/specwrk/version.rb CHANGELOG.md RELEASING.md
+git commit -m "Bump specwrk to VERSION"
+```
+
+Replace `VERSION` with the new version, for example `0.19.4`. Confirm that the
+commit contains the version and changelog updates:
+
+```sh
+git show --stat --oneline HEAD
+git status --short
+```
+
+Run the full checks:
+
+```sh
+bundle exec rake
+```
+
+Publish the release:
+
+```sh
+bundle exec rake release
+```
+
+The release task requires a clean tracked worktree and then:
+
+1. Builds `pkg/specwrk-VERSION.gem`.
+2. Creates the annotated `vVERSION` tag.
+3. Pushes `main` and the tag to `origin`.
+4. Pushes the gem to RubyGems.org.
+
+Use `gem bump` only to update the version file; use `bundle exec rake release`,
+not `gem release`, for publishing this project.
+
+If the RubyGems push fails after the tag was pushed, fix the authentication or
+network problem and rerun `bundle exec rake release`. The task recognizes the
+existing tag and retries the gem publication.
+
+## Build and publish the Docker image
+
+After the gem release succeeds, run:
+
+```sh
+scripts/build-server
+```
+
+The script reads the version from `bundle exec exe/specwrk --version`, builds the
+gem from the current checkout, and runs a multi-platform `docker buildx build`
+with `--push`. It publishes both of these tags:
+
+- `docker.io/danielwestendorf/specwrk-server:VERSION`
+- `docker.io/danielwestendorf/specwrk-server:latest`
+
+It builds images for both `linux/arm64` and `linux/amd64`. The temporary gem in
+the repository root is removed after a successful build.
+
+Verify the published manifest with:
+
+```sh
+docker buildx imagetools inspect docker.io/danielwestendorf/specwrk-server:VERSION
+```
+
+Replace `VERSION` with the released version without the `v` prefix, for example
+`0.19.4`.

data/lib/specwrk/cli.rb

@@ -67,7 +67,7 @@ module Specwrk
 
       def worker_env_for(idx)
         {
-          "TEST_ENV_NUMBER" => idx.to_s,
+          "TEST_ENV_NUMBER" => (idx == 1) ? "" : idx.to_s,
           "SPECWRK_FORKED" => idx.to_s,
           "SPECWRK_ID" => "#{ENV.fetch("SPECWRK_ID", "specwrk-worker")}-#{idx}"
         }

data/lib/specwrk/client.rb

@@ -12,6 +12,8 @@ Specwrk.net_http = Net::HTTP
 
 module Specwrk
   class Client
+    LockedResponseError = Class.new(StandardError)
+
     def self.connect?
       http = build_http
       http.start
@@ -158,10 +160,14 @@ module Specwrk
         @last_request_at = Time.now
         @http.request(request).tap do |response|
           @retry_count = 0
+          raise LockedResponseError if response.code == "423"
 
           @worker_status = response["x-specwrk-status"].to_i if response["x-specwrk-status"]
         end
       end
+    rescue LockedResponseError
+      sleep rand
+      retry
     rescue Net::ReadTimeout, Net::WriteTimeout => e
       @retry_count ||= 0
 

data/lib/specwrk/store/base.rb

@@ -4,6 +4,8 @@ require "uri"
 
 module Specwrk
   class Store
+    LockUnavailableError = Class.new(StandardError)
+
     class << self
       def with_lock(uri, key)
         adapter_klass(uri).with_lock(uri, key) { yield }

data/lib/specwrk/store/file_adapter.rb

@@ -24,11 +24,13 @@ module Specwrk
 
           lock_file = File.open(lock_file_path, "a")
 
-          Thread.pass until lock_file.flock(File::LOCK_EX)
+          locked = lock_file.flock(File::LOCK_EX | File::LOCK_NB)
+          raise LockUnavailableError unless locked
 
           yield
         ensure
-          lock_file.flock(File::LOCK_UN)
+          lock_file&.flock(File::LOCK_UN) if locked
+          lock_file&.close
         end
 
         def schedule_work(&blk)

data/lib/specwrk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Specwrk
-  VERSION = "0.19.3"
+  VERSION = "0.19.4"
 end

data/lib/specwrk/web/endpoints/base.rb

@@ -30,6 +30,8 @@ module Specwrk
           with_response.tap do |response|
             response[1]["x-specwrk-status"] = worker_status.to_s
           end
+        rescue Store::LockUnavailableError
+          locked
         end
 
         def with_response
@@ -56,6 +58,14 @@ module Specwrk
           end
         end
 
+        def locked
+          if request.head?
+            [423, {}, []]
+          else
+            [423, {"content-type" => "text/plain"}, ["Locked. Try again later."]]
+          end
+        end
+
         def payload
           return unless request.content_type&.start_with?("application/json")
           return unless request.post? || request.put? || request.delete?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: specwrk
 version: !ruby/object:Gem::Version
-  version: 0.19.3
+  version: 0.19.4
 platform: ruby
 authors:
 - Daniel Westendorf
@@ -204,6 +204,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- RELEASING.md
 - Rakefile
 - Specwrk.watchfile.rb
 - config.ru