kettle-family 1.2.62 → 1.2.63

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04321f7c14998edb27e9dd4f88d54e999bed1bdf8397678f3b3fa6d883b4c17c
-  data.tar.gz: 13af696225888e53942d50400bf35f68244591a24033d7e1398339f7e0e878a6
+  metadata.gz: 82adc3fa76e0f5e3cea98f7a02152627353175b2e0aa2b922eeb4905aee9f1a8
+  data.tar.gz: 70094edc544adbdec3240787de1c2e7c8b22e749fe8dfb9e9dca0d97253d00f3
 SHA512:
-  metadata.gz: bcf9301368288f9914849fb8cad0f5963b6d9ef984be6cca2b0e169fc2e66655ba6ffc70c5970f88a2e800fbcbcc5f46df812e150cf0b0e4a86454f013489353
-  data.tar.gz: 76cd17c2e40a09672ec728c103c3e6ee8273a97073ac85fb64f5d38cd1a9576309d41036d260e77a5eb4454435bfda99093f76f94aa9caa8f5a27d4f16bda299
+  metadata.gz: 571b5e2c915f5dcfa9e5415b6d4a0762f30c6fe005c248c7dd42285f3960f452b74fa8063c5ee05e9eddb2d116c7e5204c353eaed877428727ad238ba83e2d42
+  data.tar.gz: 7f7f630a5f1b06d17ffe8eeb5bef4a20579788bd0b4cebea30c0468763bdbba72cb8507920fe076396124b3cc91efe5ab30c683864a9d9bc4c523b5738142162

data/CHANGELOG.md

@@ -30,6 +30,44 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.2.63] - 2026-08-28
+
+- TAG: [v1.2.63][1.2.63t]
+- COVERAGE: 93.07% -- 5332/5729 lines in 33 files
+- BRANCH COVERAGE: 76.07% -- 2152/2829 branches in 33 files
+- 29.62% documented
+
+### Changed
+
+- Document release-wave dependency propagation and later-wave lockfile refresh behavior.
+
+- Document kettle-family bup as the pre-templating bundle update workflow.
+
+- Document the complete kettle-family command reference, including bup and workflow aliases.
+
+- Clarify that executed kettle-family bup runs commit successful lockfile updates unless --no-commit is supplied.
+
+- [kc] kettle-jem/prepare: updated 10 project files:
+  - configuration (1)
+  - dependencies (9)
+
+- [kc] kettle-jem/template: updated 7 project files:
+  - code and tests (1)
+  - configuration (1)
+  - dependencies (1)
+  - documentation (2)
+  - other (2)
+
+### Fixed
+
+- Reject template autostashes outside lib/, spec/, and test/ before any member is mutated.
+
+- Family release waves now refresh dependent lockfiles even when their declared dependency floors already match a newly released family version.
+
+- Restore the runtime version_gem dependency required by the version API.
+
+- Install refreshed downstream release bundles before invoking their release commands.
+
 ## [1.2.62] - 2026-08-26
 
 - TAG: [v1.2.62][1.2.62t]
@@ -2207,7 +2245,9 @@ Please file a bug if you notice a violation of semantic versioning.
 - Fixed CI load failures on engines without compatible `pty` support by falling back to Open3 for interactive release commands.
 - Fixed Ruby 3.2 version-bump support by loading Prism lazily and wiring the Prism gem only for MRI versions that need it.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.2.62...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.2.63...HEAD
+[1.2.63]: https://github.com/kettle-dev/kettle-family/compare/v1.2.62...v1.2.63
+[1.2.63t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.2.63
 [1.2.62]: https://github.com/kettle-dev/kettle-family/compare/v1.2.61...v1.2.62
 [1.2.62t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.2.62
 [1.2.61]: https://github.com/kettle-dev/kettle-family/compare/v1.2.60...v1.2.61

data/README.md

@@ -97,7 +97,9 @@ The _amazing_ test matrix is powered by the kettle-dev stack.
 
 </details>
 
-### Enterprise Support [![Tidelift](https://tidelift.com/badges/package/rubygems/kettle-family)](https://tidelift.com/subscription/pkg/rubygems-kettle-family?utm_source=rubygems-kettle-family&utm_medium=referral&utm_campaign=readme)
+### Enterprise Support
+
+[![Tidelift](https://tidelift.com/badges/package/rubygems/kettle-family)](https://tidelift.com/subscription/pkg/rubygems-kettle-family?utm_source=rubygems-kettle-family&utm_medium=referral&utm_campaign=readme)
 
 Available as part of the Tidelift Subscription.
 
@@ -260,6 +262,42 @@ completed an earlier release wave; once the dependency is available, the
 member resolves it from the registry. Release lockfile normalization always
 disables local paths regardless of this strategy.
 
+### Release waves and dependency refresh
+
+Release waves are both a sequencing mechanism and a dependency propagation
+mechanism. `kettle-family` does not start a later wave until every member in
+the current wave has succeeded. Members in one wave may run concurrently; if
+one member fails, other members already running in that wave are allowed to
+finish, but later waves do not start.
+
+After a wave succeeds during an executed publish run, `kettle-family`
+automatically reconciles declared family dependency floors in the remaining
+members. This propagation still runs when a member's declared floor already
+matches the newly released version: its lockfiles may still resolve the prior
+published release. Once all selected family dependencies of a later member have
+completed, it waits for their published versions to become available in the
+registry and runs a targeted lockfile refresh equivalent to:
+
+```console
+bundle lock --update RELEASED_MEMBER_NAMES --add-checksums
+```
+
+It then installs that exact locked bundle before starting the dependent release.
+
+The same targeted refresh is applied to the member's CI/Appraisal bundle
+lockfiles when those files are present. The refreshed lockfiles and dependency
+floor changes are committed before that member's release starts, so later
+waves test and publish against the versions produced by earlier waves rather
+than stale published versions. A resumed `--only pend` publish also reconciles
+family dependencies that were published by an earlier invocation.
+
+This propagation runs for `kettle-family release --execute --publish` when
+`release.auto_dependency_floors` is enabled (the default). It is distinct from
+`release.normalize_lockfiles`, which removes local-path and checksum problems
+before an individual release. A dry run or a standalone member
+`kettle-release` cannot update downstream family lockfiles. Registry
+propagation is retried before the family reports a dependency refresh failure.
+
 For `changelog.mode: root`, release commands pass `K_CHANGELOG_GEM_NAME` as the
 configured family name and `K_CHANGELOG_VERSION_FILE` when `version_file` is
 configured, so `kettle-changelog` can operate from a repository root without a
@@ -336,6 +374,48 @@ publish command explicitly includes `--secrets-provider`.
 
 ## 🔧 Basic Usage
 
+### Command reference
+
+The command names below are available from `kettle-family --help`:
+
+| Command | Purpose |
+|---------|---------|
+| `version` | Print the kettle-family version. |
+| `help` | Print top-level or command-specific help. |
+| `mise-trust` | Trust mise configuration for the family. |
+| `discover` | Discover members and print their execution order. |
+| `plan` | Alias for `discover`. |
+| `report` | Print family discovery and configuration details. |
+| `metadata` | Print member version, Ruby floor, license, and author metadata. |
+| `check` | Run internal read-only readiness checks. |
+| `clean-unreleased` | Uninstall locally installed family versions newer than released versions. |
+| `reconcile-releases` | Create verified missing GitHub Releases for published tags. |
+| `reset` | Reset a managed family artifact, such as release lockfiles. |
+| `test` | Run the configured test workflow for each selected member. |
+| `lint` | Run the configured lint workflow for each selected member. |
+| `docs` | Run the configured documentation workflow for each selected member. |
+| `template` | Apply the configured `kettle-jem` template for each selected member. |
+| `gha-sha-pins` | Inspect or update GitHub Actions SHA pins. |
+| `bup` | Run `bundle update --all`, or update a named dependency, per member. |
+| `bupb` | Run `bundle update --bundler` per member. |
+| `bex` | Run an arbitrary `bundle exec` command per member. |
+| `install` | Build and install selected local family gems. |
+| `bump` | Check, plan, or execute family version alignment. |
+| `bump-version` | Deprecated alias for `bump`. |
+| `add-changelog` | Add a structured entry to a member's `Unreleased` section. |
+| `release` | Prepare or publish selected member releases in dependency waves. |
+| `push` | Push selected member repositories. |
+| `pull` | Pull selected member repositories with rebase. |
+| `sync` | Fetch and rebase selected member repositories and branches. |
+| `up` | Pull with rebase, then push selected member repositories. |
+| `branch-lanes` | Audit configured long-lived release branches. |
+| `release-state` | Report release state for selected members. |
+| `state` | Alias for `release-state`. |
+
+Use `kettle-family help COMMAND` for command-specific options. Most workflow
+commands also accept `--only`, `--exclude`, `--start-at`, `--jobs`,
+`--execute`, `--dry-run`, `--commit`, and `--no-commit` as applicable.
+
 Inspect discovery and release plans before executing them:
 
 ```console
@@ -402,6 +482,22 @@ Most commands accept `--json` to print a machine-readable report instead of the
 text report, and `--report PATH` to write that JSON report while still printing
 the normal text report.
 
+Refresh member dependencies before templating when the generated project should
+be validated against the latest compatible releases:
+
+```console
+kettle-family bup --execute
+kettle-family template --execute
+```
+
+`bup` runs `bundle update --all` for every selected member. A gem name may be
+passed to update only that dependency, for example `kettle-family bup --execute
+kettle-test`. Executed updates commit successful lockfile changes by default;
+use `--no-commit` for a working-tree-only refresh, or `--commit` to state the
+default explicitly. Local dependency environment variables are preserved when
+explicitly supplied, so use the family's local or released dependency mode
+deliberately before running it.
+
 Plan or update GitHub Actions workflow SHA pins across the selected family
 members:
 
@@ -585,6 +681,14 @@ member's generated files and autostash are left in place for inspection, while
 successful or unreached members are restored normally. A successful run always
 restores its autostashes regardless of this option.
 
+Before creating any autostash, the workflow checks every selected member
+checkout. Automatic stashing is allowed only when all dirty paths are under
+`lib/`, `spec/`, or `test/`; changes elsewhere, including changelogs, lockfiles,
+configuration, and generated workflow files, fail the run before templating
+starts and are listed in the error. This preflight is separate from
+`--no-cleanup`: the latter preserves a failed template for debugging, while
+`--no-autostash` disables even the permitted source/test stashes.
+
 | Mark | Meaning |
 |------|---------|
 | `>` | A phase or command step started. |
@@ -871,7 +975,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.696-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.729-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-family/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/family/cli.rb

@@ -61,8 +61,8 @@ module Kettle
             options[:commit] = false
           end
           base.option :allow_dirty, long: "--allow-dirty", desc: "Reserved for compatibility; member repos manage their own commit safety"
-          base.option :autostash, long: "--autostash", desc: "Use the default template autostash behavior"
-          base.option :no_autostash, long: "--no-autostash", desc: "Fail template runs when a member worktree is dirty" do
+          base.option :autostash, long: "--autostash", desc: "Allow automatic stashing of eligible lib/, spec/, and test/ changes"
+          base.option :no_autostash, long: "--no-autostash", desc: "Disable automatic stashing and fail when a member worktree is dirty" do
             options[:autostash] = false
           end
         end

data/lib/kettle/family/git_status.rb

@@ -16,6 +16,13 @@ module Kettle
 
         stdout.lines.map(&:chomp).reject(&:empty?)
       end
+
+      def self.path_from_status_line(status_line)
+        line = status_line.to_s
+        path = (line.length >= 3 && line[2] == " ") ? line[3..] : line
+        path = path.to_s.strip
+        path.include?(" -> ") ? path.split(" -> ", 2).last : path
+      end
     end
   end
 end

data/lib/kettle/family/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "1.2.62"
+      VERSION = "1.2.63"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/family/workflow.rb

@@ -59,6 +59,7 @@ module Kettle
         ],
         "bupb" => %w[bundle update --bundler]
       }.freeze
+      TEMPLATE_AUTOSTASH_ALLOWED_DIRECTORIES = %w[lib spec test].freeze
       PRE_TEMPLATE_BOOTSTRAP_GEMS = %w[nomono kettle-dev].freeze
       GIT_SYNC_COMMANDS = {
         "push" => [["push", %w[git push]]],
@@ -213,6 +214,9 @@ module Kettle
         end
         checkout_preflight = [] unless checkout_preflight.all?(&:ok?)
 
+        dirty_preflight = template_dirty_worktree_preflight_results
+        return checkout_preflight + dirty_preflight unless dirty_preflight.all?(&:ok?)
+
         sync_results, stashes = template_worktree_sync_results(runner: runner)
         unless sync_results.all?(&:ok?)
           return checkout_preflight + sync_results + restore_template_autostashes(
@@ -253,8 +257,9 @@ module Kettle
         template_sync_members.each do |member|
           dirty_paths = GitStatus.dirty_paths(member.root)
           if dirty_paths.any?
-            unless autostash
-              results << template_dirty_worktree_result(member, dirty_paths)
+            blocked_paths = template_blocking_dirty_paths(dirty_paths)
+            if blocked_paths.any?
+              results << template_dirty_worktree_result(member, blocked_paths)
               break
             end
 
@@ -283,6 +288,27 @@ module Kettle
         [results, stashes]
       end
 
+      def template_dirty_worktree_preflight_results
+        template_sync_members.filter_map do |member|
+          dirty_paths = GitStatus.dirty_paths(member.root)
+          blocked_paths = template_blocking_dirty_paths(dirty_paths)
+          next if blocked_paths.empty?
+
+          template_dirty_worktree_result(member, blocked_paths)
+        end
+      end
+
+      def template_blocking_dirty_paths(dirty_paths)
+        return dirty_paths unless autostash
+
+        dirty_paths.reject { |path| template_autostash_allowed_path?(path) }
+      end
+
+      def template_autostash_allowed_path?(status_line)
+        path = GitStatus.path_from_status_line(status_line)
+        TEMPLATE_AUTOSTASH_ALLOWED_DIRECTORIES.include?(path.split("/", 2).first)
+      end
+
       def restore_template_autostashes(stashes, runner:, preserve_members: [])
         preserve_members = Array(preserve_members).map(&:to_s)
         stashes.reverse_each.map do |stash|
@@ -379,7 +405,7 @@ module Kettle
       end
 
       def template_generated_lockfile_path?(status_line)
-        path = status_line.to_s.sub(/\A.../, "").strip
+        path = GitStatus.path_from_status_line(status_line)
         [
           "Gemfile.lock",
           "Appraisal.root.gemfile.lock",
@@ -449,11 +475,17 @@ module Kettle
       end
 
       def template_dirty_worktree_result(member, dirty_paths)
+        stash_guidance = if autostash
+          "automatic template autostash is limited to lib/, spec/, and test/ files"
+        else
+          "automatic template autostash is disabled"
+        end
         template_sync_failure_result(
           member,
           [
-            "dirty worktree blocks template sync; remove --no-autostash, or commit or stash changes before retrying",
-            *dirty_paths
+            "dirty worktree blocks template sync; clean these files before retrying:",
+            *dirty_paths.map { |path| "  #{GitStatus.path_from_status_line(path)}" },
+            stash_guidance
           ].join("\n"),
           reason: "dirty worktree blocks template sync"
         )
@@ -1471,16 +1503,19 @@ module Kettle
           mode: execute ? :execute : :dry_run
         ).results
         memo.concat(floor_results)
-        return if floor_results.empty?
         return if floor_results.any? && !floor_results.all?(&:ok?)
 
         append_dependency_floor_lockfile_results(released_members: released_members, dependent_members: lockfile_ready_dependent_members, runner: runner, memo: memo)
         return if memo.any? && !memo.last.ok?
 
+        append_dependency_floor_bundle_install_results(dependent_members: lockfile_ready_dependent_members, runner: runner, memo: memo)
+        return if memo.any? && !memo.last.ok?
+
         append_dependency_floor_ci_bundle_results(released_members: released_members, dependent_members: lockfile_ready_dependent_members, runner: runner, memo: memo)
         return if memo.any? && !memo.last.ok?
 
-        commit_dependency_floor_changes(dependent_members: floor_results.map(&:member_name), runner: runner, memo: memo) if floor_results.any? && execute && commit
+        reconciled_members = (floor_results.map(&:member_name) + lockfile_ready_dependent_members.map(&:name)).uniq
+        commit_dependency_floor_changes(dependent_members: reconciled_members, runner: runner, memo: memo) if reconciled_members.any? && execute && commit
       end
 
       def dependent_members_depending_on(released_members:, dependent_members:)
@@ -1528,6 +1563,25 @@ module Kettle
         end
       end
 
+      # `bundle lock` deliberately updates only resolution metadata. Install the
+      # resulting locked bundle before invoking the dependent's `bundle exec
+      # kettle-release`, otherwise a just-published family gem can be absent
+      # from the local RubyGems installation.
+      def append_dependency_floor_bundle_install_results(dependent_members:, runner:, memo:)
+        return unless execute && publish
+        return if dependent_members.empty?
+
+        dependent_members.each do |member|
+          memo << runner.call(
+            member: member,
+            phase: "dependency_floor_bundle_install",
+            command: ["bundle", "install"],
+            env: release_lockfile_env(member)
+          )
+          break unless memo.last.ok?
+        end
+      end
+
       def wait_for_dependency_floor_lockfiles_result(member:, released_members:, runner:)
         result = nil
         REGISTRY_WAIT_ATTEMPTS.times do |index|
@@ -1811,7 +1865,7 @@ module Kettle
               "sh",
               "-lc",
               "files=$(git ls-files --modified --others --exclude-standard -- '*.gemspec' Gemfile.lock); " \
-                "if [ -n \"$files\" ]; then git add -- $files && git commit -m '⬆️ Raise family dependency floors'; fi"
+                "if [ -n \"$files\" ]; then git add -- $files && git commit -m '⬆️ Reconcile family dependencies'; fi"
             ]
           )
           break unless memo.last.ok?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.2.62
+  version: 1.2.63
 platform: ruby
 authors:
 - Peter H. Boling
@@ -74,7 +74,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.3
+        version: 1.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -84,14 +84,14 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.3
+        version: 1.0.4
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.13
+        version: 3.0.14
     - - "<"
       - !ruby/object:Gem::Version
         version: 4.0.0
@@ -101,7 +101,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.13
+        version: 3.0.14
     - - "<"
       - !ruby/object:Gem::Version
         version: 4.0.0
@@ -114,7 +114,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.13
+        version: 0.3.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -124,7 +124,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.13
+        version: 0.3.14
 - !ruby/object:Gem::Dependency
   name: kettle-jem
   requirement: !ruby/object:Gem::Requirement
@@ -154,7 +154,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.20
+        version: 2.0.21
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -164,7 +164,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.20
+        version: 2.0.21
 - !ruby/object:Gem::Dependency
   name: tsort
   requirement: !ruby/object:Gem::Requirement
@@ -324,7 +324,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.5
+        version: 3.2.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -334,7 +334,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.5
+        version: 3.2.6
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -378,7 +378,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -388,7 +388,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.11
+        version: 2.0.12
 description: "\U0001F469‍\U0001F469‍\U0001F467‍\U0001F467 Kettle::Family provides
   scripts and conventions for coordinating related Ruby gems as one family."
 email:
@@ -441,10 +441,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-family.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.2.62
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.2.62/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.2.63
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.2.63/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.2.62
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.2.63
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-family/wiki
   news_uri: https://www.railsbling.com/tags/kettle-family