plan_my_stuff 0.29.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98cbaeb499aa1b3b22018b7145d2d8e0bd86051a237230d1b5cac3e884109e10
-  data.tar.gz: a66aa1aec786adca0853eed340e1f35e2639c7aca6aafae88a421b4cc2136b5d
+  metadata.gz: 3993e1306f27793791833787c546d81a42ed7bdf23d1420a658ec3877acf284b
+  data.tar.gz: 4593de2a00ea81ad22d0d951e1a97eb858a3d26071510c42e2e1aab9b99ae0f8
 SHA512:
-  metadata.gz: 8f4e1995d828ae83edfc94a9d2d0805b5787165e28f062bd0100f586de2c19e49fb6f9167ac0ee0ea88be5001012ffab5371315d2dcaee4b081a13e6be53a993
-  data.tar.gz: 95474b37f6f2bbd4c6074f3049086b1d643617c7c0a6dbf8562e9e0c29f9ad7bcbcabcedfda29f8e55cfcf12d5f0024a41cd69d0c9527dff91948a83e8dcde46
+  metadata.gz: a9e140d9c6371186961903c5251143a63f4bedb3c238fc2d2b69e25ef3263824bdeacf767494c46473a5c7e9560c50b057e9b82136505b3615bcacdc742b3b6c
+  data.tar.gz: f73cb36b19ced07d713ae6e1aee02ab314292b3410d8b14d160e2156ceedd4a202f2fcecff7f67b61d25c93887bbc7e694f4415b89bab1203faa1e8bf7d7566c

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.0.0
+
+Official release.
+
+### Breaking
+
+- `MetadataParser.parse` no longer recognizes the legacy `<!-- pms-metadata:... -->` HTML-comment format.
+  Bodies written before 0.17.0 that have not been re-saved will now be returned as plain body text with
+  empty metadata. The deprecation warning emitted by 0.17.0+ has been removed along with the legacy
+  pattern.
+- Removed the deprecated `IssueMetadata#priority_list`, `#priority_list=`, `#priority_list?`,
+  `#priority_list_priority`, and `#priority_list_priority=` accessors, along with the legacy-write forwarding
+  that turned `metadata.priority_list = true` into `Priority List` / `Priority List Priority` issue-field writes
+  on `save!` / `update!` / `create!`. Use `Issue#priority_list?` / `#priority_list_priority` for reads and
+  `Issue#add_to_priority_list!(priority: N)` / `#remove_from_priority_list!` for writes (closes #57).
+- `CommentMetadata` no longer parses the legacy `{filename, url}` attachment shape into structured fields.
+  Entries must now carry the `{filename, owner, repo, sha, path}` shape; legacy entries that were never
+  re-saved are dropped as malformed. The `LEGACY_URL_REGEXES` / `LEGACY_ATTACHMENT_DEPRECATION_MESSAGE`
+  constants and the migrate-on-write deprecation warning have been removed.
+
+## 0.30.0
+
+### Added
+
+- The AWS deployment-completed webhook now fires a single `pipeline_deployment_completed.plan_my_stuff` batch event
+  after the per-item sweep, carrying every item that actually transitioned (payload: `:project_items`, `:issue_numbers`,
+  `:commit_sha`). Per-item `pipeline_completed.plan_my_stuff` events still fire. The batch event is skipped when nothing
+  transitioned, giving subscribers (release-notes mailer, Slack summary, changelog generator) one clean
+  "deployment finished" signal without debouncing N per-item events (closes #97).
+
+### Changed
+
+- `PlanMyStuff::Notifications.instrument` now accepts an `Array` resource. The payload key is the pluralized element
+  key (a batch of project items keys as `:project_items`, a batch of issues as `:issues`), so batch events carry a full
+  set under one key.
+- `PlanMyStuff::Pipeline.instrument` now accepts an `Array` of items for a batch event; the payload carries
+  `:issue_numbers` (the linked number of every item) in place of the single-item `:issue_number`.
+
 ## 0.29.0
 
 ### Changed

data/README.md

@@ -612,12 +612,20 @@ Cache keys include both the gem's `CACHE_VERSION` ("v1") and `config.cache_versi
 
 ## Metadata
 
-All state lives on GitHub. Each domain class carries a typed metadata object hidden in the corresponding GitHub body (issue/comment body, project readme) as an HTML comment that's invisible when rendered on github.com:
+All state lives on GitHub. Each domain class carries a typed metadata object embedded in the corresponding GitHub
+body (issue/comment body, project readme) as a collapsible `<details>` block containing a JSON code fence, which
+GitHub renders in-page:
 
-```html
-<!-- pms-metadata:{"schema_version":1,"gem_version":"0.0.0","app_name":"MyApp",...} -->
+````markdown
+<details><summary>pms-metadata</summary>
+
+```json
+{"schema_version":1,"gem_version":"0.0.0","app_name":"MyApp", ...}
 ```
 
+</details>
+````
+
 `MetadataParser` strips the block out of the raw body on read and re-inserts it on write — callers see `issue.body` (human text) and `issue.metadata` (typed object) separately.
 
 ### Metadata classes
@@ -698,7 +706,15 @@ The engine mounts two webhook endpoints when the pipeline is enabled:
 - `POST /webhooks/github` — takes GitHub `pull_request` events. On `closed` against a tracked branch, the gem calls `IssueLinker` to extract `#123` references from the PR body and commit messages, then transitions each linked issue (e.g. merged to main -> `start_deployment!`).
 - `POST /webhooks/aws` — takes CodeDeploy/SNS lifecycle events. On a successful deployment, the gem flips matching items to `Completed`.
 
-See `designs/release_cycle/plan.md` for the full design, including the `projects_v2_item` path that fires `Pipeline.take!` when a human drags an item to Started on github.com.
+On a successful AWS deployment the gem completes each matching item individually (one
+`pipeline_completed.plan_my_stuff` event apiece), then fires a single
+`pipeline_deployment_completed.plan_my_stuff` batch event carrying every item that actually transitioned
+(payload: `:project_items`, `:issue_numbers`, `:commit_sha`). It is skipped when nothing transitioned, so subscribers
+(release-notes mailer, Slack summary, changelog generator) get one clean "deployment finished" signal
+without debouncing the per-item events.
+
+See `designs/release_cycle/plan.md` for the full design, including the `projects_v2_item` path that fires
+`Pipeline.take!` when a human drags an item to Started on github.com.
 
 ### "Take" button
 

data/app/controllers/plan_my_stuff/webhooks/aws_controller.rb

@@ -147,7 +147,10 @@ module PlanMyStuff
         end
 
         # Finds "Release in Progress" items whose linked issue commit SHA matches the configured production
-        # commit SHA (prefix match), then completes deployment for each.
+        # commit SHA (prefix match), then completes deployment for each. After the per-item sweep, fires one batch
+        # +pipeline_deployment_completed.plan_my_stuff+ event carrying every item that actually transitioned
+        # (+complete_deployment!+ returns +nil+ when auto-complete is off, so those are excluded). The batch event is
+        # skipped when nothing transitioned so subscribers only see real deployments.
         #
         # @return [void]
         #
@@ -162,13 +165,22 @@ module PlanMyStuff
             return
           end
 
-          release_in_progress_items.each do |item|
+          completed_items = release_in_progress_items.filter_map do |item|
             next if item.draft?
 
             next unless item.issue.metadata.commit_sha&.start_with?(sha)
 
-            PlanMyStuff::Pipeline.complete_deployment!(item)
+            result = PlanMyStuff::Pipeline.complete_deployment!(item)
+            item if result.present?
           end
+
+          return if completed_items.empty?
+
+          PlanMyStuff::Pipeline.instrument(
+            'deployment_completed',
+            completed_items,
+            commit_sha: sha,
+          )
         end
 
         # Finds all pipeline project items at "Release in Progress" status.

data/lib/plan_my_stuff/comment_metadata.rb

@@ -2,17 +2,6 @@
 
 module PlanMyStuff
   class CommentMetadata < PlanMyStuff::BaseMetadata
-    LEGACY_URL_REGEXES = [
-      %r{\Ahttps://raw\.githubusercontent\.com/(?<owner>[^/\s]+)/(?<repo>[^/\s]+)/(?<sha>[^/\s]+)/(?<path>.+)\z},
-      %r{\Ahttps://github\.com/(?<owner>[^/\s]+)/(?<repo>[^/\s]+)/blob/(?<sha>[^/\s]+)/(?<path>.+)\z},
-    ].freeze
-
-    LEGACY_ATTACHMENT_DEPRECATION_MESSAGE =
-      'PlanMyStuff: legacy attachment metadata shape {filename, url} detected. It will continue to parse ' \
-        'until 1.0.0, at which point legacy detection will be removed. New writes use the structured ' \
-        '{filename, owner, repo, sha, path} shape introduced in #70; existing entries migrate on their ' \
-        'next write.'
-
     # @return [Boolean] true if this comment holds the issue's body content
     attr_accessor :issue_body
     # @return [Array<PlanMyStuff::Attachment>] consuming-app attachment records associated with this comment
@@ -95,11 +84,7 @@ module PlanMyStuff
       # Builds a +PlanMyStuff::Attachment+ from each parsed entry.
       # Accepts:
       # - an existing +PlanMyStuff::Attachment+
-      # - the new shape +{filename:, owner:, repo:, sha:, path:}+
-      # - the legacy shape +{filename:, url:}+ where +url+ is a raw
-      #   +raw.githubusercontent.com+ permalink or a +github.com/.../blob/...+
-      #   blob-viewer URL; parsed once into structured fields so the
-      #   next write drops the +url+ key (migrate-on-write).
+      # - the structured shape +{filename:, owner:, repo:, sha:, path:}+
       #
       # Malformed hash entries are silently dropped so a single bad
       # historical entry doesn't crash +Comment.find+. An already-
@@ -118,45 +103,17 @@ module PlanMyStuff
             if entry.is_a?(PlanMyStuff::Attachment)
               entry
             elsif entry.respond_to?(:transform_keys)
-              PlanMyStuff::Attachment.new(structured_attrs(entry.transform_keys(&:to_sym)))
+              PlanMyStuff::Attachment.new(entry.transform_keys(&:to_sym))
             end
           next if attachment.nil?
 
           attachment.validate!
           attachment
-        rescue ActiveModel::ValidationError, ArgumentError
+        rescue ActiveModel::ValidationError, ActiveModel::UnknownAttributeError, ArgumentError
           raise if entry.is_a?(PlanMyStuff::Attachment)
 
           next
         end
       end
-
-      # Returns +attrs+ untouched when it already carries structured
-      # fields, otherwise parses a legacy +url+ into
-      # +owner+/+repo+/+sha+/+path+. Unparseable URLs yield a hash
-      # with no structured fields, leaving +Attachment+ validation to
-      # drop the entry.
-      #
-      # @param attrs [Hash{Symbol=>Object}]
-      #
-      # @return [Hash{Symbol=>Object}]
-      #
-      def structured_attrs(attrs)
-        return attrs if attrs.key?(:owner)
-
-        PlanMyStuff.deprecator.warn(LEGACY_ATTACHMENT_DEPRECATION_MESSAGE)
-
-        url = attrs[:url].to_s
-        match = LEGACY_URL_REGEXES.lazy.filter_map { |re| re.match(url) }.first
-
-        return attrs.except(:url) if match.nil?
-
-        attrs.except(:url).merge(
-          owner: match[:owner],
-          repo: match[:repo],
-          sha: match[:sha],
-          path: match[:path],
-        )
-      end
   end
 end

data/lib/plan_my_stuff/issue.rb

@@ -901,8 +901,6 @@ module PlanMyStuff
     # @return [self]
     #
     def save!(user: nil, skip_notification: false)
-      forward_legacy_priority_list_metadata!
-
       if new_record?
         created = self.class.create!(
           title: title,
@@ -1243,28 +1241,6 @@ module PlanMyStuff
         reload
       end
 
-      # Forwards a pending legacy +metadata.priority_list+ /
-      # +#priority_list_priority+ write into +@pending_issue_fields+ so the next
-      # +save!+ persists the values into the +Priority List+ /
-      # +Priority List Priority+ GitHub Issue Fields. Caller-supplied
-      # +issue_fields:+ entries win on key collision. Silently skipped when
-      # +config.issue_fields_enabled+ is +false+.
-      #
-      # @return [void]
-      #
-      def forward_legacy_priority_list_metadata!
-        return unless PlanMyStuff.configuration.issue_fields_enabled
-        return unless metadata.instance_variable_get(:@legacy_priority_list_pending)
-
-        legacy_pl = metadata.instance_variable_get(:@priority_list)
-        legacy_plp = metadata.instance_variable_get(:@priority_list_priority)
-
-        legacy_fields = { 'Priority List' => legacy_pl ? 'Yes' : nil }
-        legacy_fields['Priority List Priority'] = legacy_plp unless legacy_plp == -1
-
-        @pending_issue_fields = legacy_fields.merge(@pending_issue_fields || {})
-      end
-
       # Applies in-memory updates from an +update!+ kwargs hash. Top-level scalars go through their setters so
       # +@body_dirty+ and friends stay in sync; +metadata:+ is merged into +@metadata+ (top-level attrs assigned
       # directly, custom_fields merged key-by-key).

data/lib/plan_my_stuff/issue_metadata.rb

@@ -2,13 +2,6 @@
 
 module PlanMyStuff
   class IssueMetadata < PlanMyStuff::BaseMetadata
-    PRIORITY_LIST_METADATA_DEPRECATION =
-      'PlanMyStuff: IssueMetadata#priority_list / #priority_list_priority are deprecated. priority_list moved to ' \
-        "GitHub Issue Fields ('Priority List' single_select, 'Priority List Priority' number) in 0.20.0. Reads " \
-        'now come from Issue#priority_list? / #priority_list_priority; for writes, use ' \
-        'Issue#add_to_priority_list!(priority: N) and Issue#remove_from_priority_list!. The metadata accessors ' \
-        'will be removed in 1.0.0.'
-
     # @return [Time, nil] first support action timestamp, nil until set
     attr_accessor :responded_at
     # @return [String, nil] user-facing URL in the consuming app
@@ -53,14 +46,6 @@ module PlanMyStuff
 
         metadata.responded_at = parse_time(hash[:responded_at])
         metadata.issues_url = hash[:issues_url]
-        if hash.key?(:priority_list) || hash.key?(:priority_list_priority)
-          PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-          metadata.instance_variable_set(:@priority_list, hash[:priority_list]) if hash.key?(:priority_list)
-          if hash.key?(:priority_list_priority)
-            metadata.instance_variable_set(:@priority_list_priority, hash[:priority_list_priority])
-          end
-          metadata.instance_variable_set(:@legacy_priority_list_pending, true)
-        end
         metadata.visibility_allowlist = Array.wrap(hash[:visibility_allowlist])
         metadata.commit_sha = hash[:commit_sha]
         metadata.auto_complete = hash.fetch(:auto_complete, true)
@@ -193,57 +178,6 @@ module PlanMyStuff
       !!auto_complete
     end
 
-    # @deprecated Use +Issue#priority_list?+. Removed in 1.0.0.
-    #
-    # @return [Object, nil]
-    #
-    def priority_list
-      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-      @priority_list
-    end
-
-    # @deprecated Use +Issue#add_to_priority_list!(priority: N)+ / +Issue#remove_from_priority_list!+. Removed in 1.0.0.
-    #
-    # @param value [Object]
-    #
-    # @return [Object]
-    #
-    def priority_list=(value)
-      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-      @legacy_priority_list_pending = true
-      @priority_list = value
-    end
-
-    # @deprecated Use +Issue#priority_list?+. Removed in 1.0.0.
-    #
-    # @return [Boolean]
-    #
-    def priority_list?
-      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-      !!@priority_list
-    end
-
-    # @deprecated Use +Issue#priority_list_priority+. Removed in 1.0.0.
-    #
-    # @return [Object, nil]
-    #
-    def priority_list_priority
-      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-      @priority_list_priority
-    end
-
-    # @deprecated Use +Issue#add_to_priority_list!(priority: N)+ / +Issue#remove_from_priority_list!+. Removed in 1.0.0.
-    #
-    # @param value [Object]
-    #
-    # @return [Object]
-    #
-    def priority_list_priority=(value)
-      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
-      @legacy_priority_list_pending = true
-      @priority_list_priority = value
-    end
-
     # @return [Boolean]
     def responded?
       !responded_at.nil?

data/lib/plan_my_stuff/metadata_parser.rb

@@ -1,17 +1,11 @@
 # frozen_string_literal: true
 
-require 'active_support/deprecation'
 require 'json'
 
 module PlanMyStuff
   module MetadataParser
-    LEGACY_DEPRECATION_MESSAGE =
-      'PlanMyStuff: legacy <!-- pms-metadata: ... --> body format detected. It will continue to parse ' \
-        'until 1.0.0, at which point legacy detection will be removed. New writes already use the visible ' \
-        '<details> block format introduced in 0.17.0; existing bodies migrate on their next write.'
-
-    # New format: collapsible <details> block containing a JSON code fence.
-    # Renders visibly on GitHub (issue #58) instead of being hidden in an HTML comment.
+    # Collapsible <details> block containing a JSON code fence. Renders visibly on
+    # GitHub (issue #58) instead of being hidden in an HTML comment.
     METADATA_PATTERN = %r{
       \A<details><summary>pms-metadata</summary>\n\n
       ```json\n(.*?)\n```\n\n
@@ -27,10 +21,6 @@ module PlanMyStuff
       </details>\n*
     }mx
 
-    # Legacy format kept for parsing only - existing issues serialized before 0.17.0
-    # used a hidden HTML comment. They migrate to the new format on the next write.
-    LEGACY_METADATA_PATTERN = /\A<!-- pms-metadata:(.*?) -->\n*/m
-
     module_function
 
     # Extracts metadata JSON from the raw body
@@ -41,15 +31,11 @@ module PlanMyStuff
     #
     def parse(raw_body)
       return { metadata: {}, body: '' } if raw_body.blank?
+      return { metadata: {}, body: raw_body } unless raw_body.match?(METADATA_PATTERN)
 
-      pattern = matching_pattern(raw_body)
-      return { metadata: {}, body: raw_body } if pattern.nil?
-
-      PlanMyStuff.deprecator.warn(LEGACY_DEPRECATION_MESSAGE) if pattern == LEGACY_METADATA_PATTERN
-
-      match = raw_body.match(pattern)
+      match = raw_body.match(METADATA_PATTERN)
       metadata = JSON.parse(match[1], symbolize_names: true)
-      body = raw_body.sub(pattern, '').sub(ATTACHMENTS_PATTERN, '')
+      body = raw_body.sub(METADATA_PATTERN, '').sub(ATTACHMENTS_PATTERN, '')
 
       { metadata: metadata, body: body }
     rescue JSON::ParserError
@@ -102,14 +88,5 @@ module PlanMyStuff
       safe_filename = attachment[:filename].to_s.gsub(']', '\]')
       "- [#{safe_filename}](#{url})"
     end
-
-    # @param raw_body [String]
-    #
-    # @return [Regexp, nil] the pattern that matches at the start of +raw_body+, or +nil+ when neither matches
-    #
-    def matching_pattern(raw_body)
-      return METADATA_PATTERN if raw_body.match?(METADATA_PATTERN)
-      return LEGACY_METADATA_PATTERN if raw_body.match?(LEGACY_METADATA_PATTERN)
-    end
   end
 end

data/lib/plan_my_stuff/notifications.rb

@@ -21,7 +21,8 @@ module PlanMyStuff
     # Fires +<event>.plan_my_stuff+ with a normalized payload.
     #
     # @param event [String] e.g. +'issue_created'+
-    # @param resource [Object] domain object (+Issue+, +Comment+, +ProjectItem+, ...)
+    # @param resource [Object] domain object (+Issue+, +Comment+, +ProjectItem+, ...), or an +Array+ of resources for a
+    #   batch event (keyed by the pluralized element key, e.g. +:project_items+)
     # @param user [Object, nil] explicit actor; falls back to +config.current_user+
     # @param extra [Hash] additional payload entries (+changes:+, +labels:+, +user_ids:+, ...)
     #
@@ -63,7 +64,9 @@ module PlanMyStuff
       payload.merge(extra)
     end
 
-    # Maps a resource object to its payload key.
+    # Maps a resource object to its payload key. An +Array+ recurses on its first element and pluralizes that key, so
+    # batch events carry the full set under one key (a batch of project items keys as +:project_items+, a batch of
+    # issues as +:issues+, an empty/unknown batch as +:resources+).
     #
     # @param resource [Object]
     #
@@ -74,6 +77,7 @@ module PlanMyStuff
       when PlanMyStuff::Issue then :issue
       when PlanMyStuff::Comment then :comment
       when PlanMyStuff::BaseProjectItem then :project_item
+      when Array then :"#{infer_resource_key(resource.first)}s"
       else :resource
       end
     end

data/lib/plan_my_stuff/pipeline.rb

@@ -55,13 +55,17 @@ module PlanMyStuff
     # canonical status is added to the payload as +:status+. Otherwise +event+ is used verbatim as the suffix (e.g.
     # +"removed"+, +"removed_late"+, +"testing"+).
     #
+    # +resource+ is normally a single project item (payload carries +:issue_number+). Pass an +Array+ for a batch
+    # event (e.g. the deployment-completed sweep) and the payload instead carries +:issue_numbers+ -- the linked
+    # number of every item.
+    #
     # @param event [String] status name or literal event suffix
-    # @param project_item [PlanMyStuff::BaseProjectItem]
+    # @param resource [PlanMyStuff::BaseProjectItem, Array<PlanMyStuff::BaseProjectItem>] item or batch of items
     # @param extra [Hash] additional payload entries
     #
     # @return [void]
     #
-    def instrument(event, project_item, **extra)
+    def instrument(event, resource, **extra)
       extra_to_use = { **extra }
       event_to_use = event
       if PlanMyStuff::Pipeline::Status::ALL.include?(event_to_use)
@@ -69,10 +73,17 @@ module PlanMyStuff
         event_to_use = PlanMyStuff::Pipeline::Status.key_for(event_to_use)
       end
 
+      number_fields =
+        if resource.is_a?(Array)
+          { issue_numbers: resource.map(&:number) }
+        else
+          { issue_number: resource.number }
+        end
+
       PlanMyStuff::Notifications.instrument(
         "pipeline_#{event_to_use}",
-        project_item,
-        issue_number: project_item.number,
+        resource,
+        **number_fields,
         **extra_to_use,
       )
     end

data/lib/plan_my_stuff/version.rb

@@ -2,8 +2,8 @@
 
 module PlanMyStuff
   module VERSION
-    MAJOR = 0
-    MINOR = 29
+    MAJOR = 1
+    MINOR = 0
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Brands Insurance