yard-timekeeper 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8189ecebef7b48bb893bca74e80d438ee129bc78aec9cae83da4c668ffd9d03
-  data.tar.gz: 1f50ff152d50ae640e57dadea52ff852e4294b50328d6840ad6dbcfde3a05336
+  metadata.gz: 865e7e350c522be374670622f6f78849725e0c34e4f70e9736cf0d0d95d93ecb
+  data.tar.gz: ca58d1226036bf5f64ce43815d54f6f628640bb470462e56f5340808df3c508c
 SHA512:
-  metadata.gz: a9575b79922a00fbb3acae19774091d8231174a15d279cec047336c6028a45cf4c952dc5fa4af3e0ceaafe75f9e3ed424bccbb373538370b4572ba26cedd2b12
-  data.tar.gz: de2f78f096cef1b842c0882a001bf58eb7c4eb72f6a76020fb22ed35e0feaa2475bf7c5c35a9f20acca9288d460bfa12a39c709b21a2e68bbd0e2ed5a02329a7
+  metadata.gz: 6648fe7c779062819edaee95af6e456663b1fb73d45e05b9385308d8ae09d1766165af924a21eb2b4f1dea347770dec80f68a9e23818bfc276b9a2c362c2ba38
+  data.tar.gz: 895058166ceba097ea730336d5deef19e2b20ea73cead4cd21222c2090fee4a9424adb3cbf3f38b016bf6c80628b66a49a919f0d416335d369bf2caf6401f580

data/CHANGELOG.md

@@ -30,6 +30,19 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.2.1] - 2026-06-04
+
+- TAG: [v0.2.1][0.2.1t]
+- COVERAGE: 98.80% -- 82/83 lines in 2 files
+- BRANCH COVERAGE: 93.33% -- 28/30 branches in 2 files
+- 20.83% documented
+
+### Fixed
+
+- Treated YARD generator version and Ruby version footer changes as generated
+  documentation churn, so footer-only docs diffs are restored even when the
+  toolchain version changes.
+
 ## [0.2.0] - 2026-06-03
 
 - TAG: [v0.2.0][0.2.0t]
@@ -80,7 +93,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.2.0...v0.2.1
+[0.2.1t]: https://github.com/galtzo-floss/yard-timekeeper/releases/tag/v0.2.1
 [0.2.0]: https://github.com/galtzo-floss/yard-timekeeper/compare/v0.1.0...v0.2.0
 [0.2.0t]: https://github.com/galtzo-floss/yard-timekeeper/releases/tag/v0.2.0
 [0.1.0]: https://github.com/galtzo-floss/yard-timekeeper/compare/bffde1dbf4ceb71a29a72b5b2dfb79622a14417b...v0.1.0

data/README.md

@@ -22,13 +22,15 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 ## 🌻 Synopsis <a href="https://discord.gg/3qme4XHNKN"><img alt="Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px.svg" width="8%" align="right"/></a> <a href="https://ruby-toolbox.com"><img alt="ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5" src="https://logos.galtzo.com/assets/images/ruby-lang/avatar-128px.svg" width="8%" align="right"/></a>
 
 `yard-timekeeper` keeps checked-in YARD HTML stable by restoring files whose
-only change is the generated footer timestamp.
+only changes are generated footer churn.
 
 Just the important bits:
 
 - It postprocesses generated `docs/**/*.html` files after YARD finishes.
 - It only restores files that are already tracked in git and only when the diff
-  is timestamp-only.
+  is limited to generated footer metadata.
+- It treats YARD footer timestamp, YARD version, and Ruby version changes as
+  generated churn, because those do not represent documentation content changes.
 - Real content changes are preserved.
 - The supported workflow is `rake yard`; raw `yard` / `bin/yard` does not run
   the explicit postprocess hook.
@@ -127,20 +129,32 @@ Yard::Timekeeper.install_rake_tasks!(:yard)
 ```
 
 `yard-timekeeper` runs after YARD generates HTML and checks git diffs for tracked
-files under `docs/`. If a file's only change is the footer line:
+files under `docs/`. If a file's only changes are generated footer metadata:
 
 ```text
 Generated on ...
+0.9.44 (ruby-4.0.5).
 ```
 
 then the plugin restores that file from git so the docs site does not churn for
-timestamp-only changes.
+toolchain-only changes.
+
+This protects against the common case where rebuilding docs changes only:
+
+- the generation timestamp
+- the YARD generator version
+- the Ruby version in the YARD footer
+
+Those values are useful when the page content changes, but they are not useful
+as standalone repository diffs.
 
 Notes:
 
 - It only affects files already tracked in git.
 - It is most useful for checked-in `docs/` sites.
 - Files with any real content changes keep their fresh timestamp.
+- Files with source, README, changelog, API, or rendered markup changes are not
+  restored just because their footer also changed.
 
 Environment toggles:
 
@@ -154,6 +168,10 @@ Generate docs through rake so the postprocess runs after YARD finishes:
 bin/rake yard
 ```
 
+After generation, `yard-timekeeper` examines each changed tracked HTML file
+under `docs/`. Footer-only churn is restored from git automatically. Pages with
+real rendered content changes remain modified, including their fresh footer.
+
 If your project also exposes `bin/yard`, do not rely on it for the full docs
 workflow. It runs YARD, but it does not run
 `Yard::Timekeeper.install_rake_tasks!(:yard)`.
@@ -506,7 +524,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-0.072-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.083-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/galtzo-floss/yard-timekeeper/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/yard/timekeeper/version.rb

@@ -3,7 +3,7 @@
 module Yard
   module Timekeeper
     module Version
-      VERSION = "0.2.0"
+      VERSION = "0.2.1"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

data/lib/yard/timekeeper.rb

@@ -15,6 +15,12 @@ module Yard
     RAKE_INTEGRATIONS_MUTEX = Mutex.new
 
     TIMESTAMP_DIFF_LINE_RE = /\A[+-]\s{2}Generated on .+ by\s*\z/
+    GENERATOR_VERSION_DIFF_LINE_RE = /
+      \A[+-]\s{2}
+      \d+(?:\.\d+)+(?:[.\w-][.\w-]*)?
+      \s\(ruby-[^)]+\)\.\s*
+      \z
+    /x
     DIFF_METADATA_PREFIXES = [
       "diff --git ",
       "index ",
@@ -111,14 +117,33 @@ module Yard
           next if DIFF_METADATA_PREFIXES.any? { |prefix| line.start_with?(prefix) }
           next if line.strip.empty?
 
-          return false unless line.match?(TIMESTAMP_DIFF_LINE_RE)
+          return false unless footer_churn_line?(line)
 
           change_lines << line
         end
 
-        change_lines.size == 2 &&
-          change_lines.one? { |line| line.start_with?("-") } &&
-          change_lines.one? { |line| line.start_with?("+") }
+        balanced_footer_churn?(change_lines)
+      end
+
+      def footer_churn_line?(line)
+        line.match?(TIMESTAMP_DIFF_LINE_RE) || line.match?(GENERATOR_VERSION_DIFF_LINE_RE)
+      end
+
+      def balanced_footer_churn?(change_lines)
+        removed_lines = change_lines.select { |line| line.start_with?("-") }
+        added_lines = change_lines.select { |line| line.start_with?("+") }
+
+        removed_lines.size == added_lines.size &&
+          removed_lines.size.between?(1, 2) &&
+          removed_lines.map { |line| footer_churn_kind(line) }.sort ==
+            added_lines.map { |line| footer_churn_kind(line) }.sort
+      end
+
+      def footer_churn_kind(line)
+        return :timestamp if line.match?(TIMESTAMP_DIFF_LINE_RE)
+        return :generator_version if line.match?(GENERATOR_VERSION_DIFF_LINE_RE)
+
+        :unknown
       end
 
       def restore_file(path, root)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-timekeeper
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -278,10 +278,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://yard-timekeeper.galtzo.com
-  source_code_uri: https://github.com/galtzo-floss/yard-timekeeper/tree/v0.2.0
-  changelog_uri: https://github.com/galtzo-floss/yard-timekeeper/blob/v0.2.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/yard-timekeeper/tree/v0.2.1
+  changelog_uri: https://github.com/galtzo-floss/yard-timekeeper/blob/v0.2.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/yard-timekeeper/issues
-  documentation_uri: https://www.rubydoc.info/gems/yard-timekeeper/0.2.0
+  documentation_uri: https://www.rubydoc.info/gems/yard-timekeeper/0.2.1
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/yard-timekeeper/wiki
   news_uri: https://www.railsbling.com/tags/yard-timekeeper