plan_my_stuff 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15988155f3d1798b5b0f43cbb1597f7e8b7ed881feb3db2504da7ecd74ab9c59
-  data.tar.gz: 35f298dce675a86ca15153a354411c23806e8420374fe5eb4fd7d2c392e0ed9d
+  metadata.gz: 06744d7c7bc63206522ce6d7c9176eeb8e93fabb4de903d7df32b17cfae6948d
+  data.tar.gz: 2338f2f85989b2ee3b29a48c114a82d36c8105c13e4caf19b2601ff02cbf063c
 SHA512:
-  metadata.gz: 838ebf5cb77a3467fb291d76acd9b2ded4cc40d88e65673ca41374324736c6cdc11e5bbc0ed7e04eaf0c0bb5ac4f799c3052379cdc87edcd7343dc30be370059
-  data.tar.gz: b30d829c2255b61485c72d639992f1095f9726b7e6d8952114eef2e44c91f1016c0f05bd3abd238faf0be83a37c8b75ef492208351d33cbbe1f2f689270e7614
+  metadata.gz: dd143db048f77a46fe7875b1592b9ff1dc26e6ddac13af60c177ae977f799606d172a23ca861222a1a133d53fb91d16be19dd40d8f7027b680316276d99088f0
+  data.tar.gz: 607957cf66e887c31bb6ab3f9a93726da0cf853cb3d43e8d34857b0dd789981788de4f0c8c6e076ad5236141732867ed9641971dcc683df5e4683e6b726542f3

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.20.0
+
+### Breaking
+
+- `priority_list` and `priority_list_priority` keys removed from `IssueMetadata` serialization. Existing issues
+  migrate to the GitHub Issue Field equivalents (`Priority List`, `Priority List Priority`) on their next save.
+
+### Added
+
+- `Issue#priority_list?` and `Issue#priority_list_priority` read the corresponding issue field values directly.
+- `Issue.priority_list(repo:, state:, labels:, page:, per_page:)` convenience method delegates to
+  `Issue.list(priority_list: true, ...)`.
+- `Issue.list` and `Issue.count` accept `priority_list:` for server-side filtering via the GitHub issue fields
+  API (passes `priority_list: false` raises `ArgumentError` -- the API has no negation qualifier).
+
+### Deprecated
+
+- `IssueMetadata#priority_list`, `#priority_list=`, `#priority_list?`, `#priority_list_priority`, and
+  `#priority_list_priority=` emit deprecation warnings on each read/write. Legacy writes forward to the issue
+  field on `Issue#save!` / `#update!` / `Issue.create!`. The accessors will be removed in 1.0.0.
+
 ## 0.19.0
 
 ### Added

data/lib/plan_my_stuff/issue.rb

@@ -296,26 +296,46 @@ module PlanMyStuff
 
       # Lists GitHub issues with optional filters and pagination.
       #
+      # @raise [ArgumentError] when +priority_list: false+ is passed
+      #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +issue_field_values+ query param). +false+ raises +ArgumentError+ -- GitHub
+      #   has no negation qualifier. Silently dropped when +config.issue_fields_enabled+ is +false+.
       # @param page [Integer]
       # @param per_page [Integer]
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
+      def list(repo: nil, state: :open, labels: [], priority_list: nil, page: 1, per_page: 25)
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo!(repo)
 
         params = { state: state.to_s, page: page, per_page: per_page }
         params[:labels] = labels.sort.join(',') if labels.present?
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          params[:issue_field_values] = 'priority-list:Yes'
+        end
 
         github_issues = client.rest(:list_issues, resolved_repo, **params)
         filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
         filtered.map { |gi| build(gi, repo: resolved_repo) }
       end
 
+      # Convenience shortcut for +list(priority_list: true, ...)+. See +.list+ for parameter semantics.
+      #
+      # @return [Array<PlanMyStuff::Issue>]
+      #
+      def priority_list(**)
+        list(**, priority_list: true)
+      end
+
       # Counts GitHub issues matching the given filters without paginating full payloads.
       #
       # Uses GitHub's Search API (+search/issues+), which returns +total_count+ in a single
@@ -327,13 +347,23 @@ module PlanMyStuff
       # - The Search API has its own rate limit (30 req/min authenticated) separate from
       #   the core REST API.
       #
+      # @raise [ArgumentError] when +priority_list: false+ is passed
+      #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +field.priority-list:Yes+ Search qualifier). +false+ raises
+      #   +ArgumentError+ -- GitHub has no negation qualifier. Silently dropped when
+      #   +config.issue_fields_enabled+ is +false+.
       #
       # @return [Integer]
       #
-      def count(repo: nil, state: :open, labels: [])
+      def count(repo: nil, state: :open, labels: [], priority_list: nil)
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo!(repo)
 
@@ -344,7 +374,12 @@ module PlanMyStuff
         qualifiers += labels_to_use.map do |label|
           "label:\"#{label}\""
         end
-        client.rest(:search_issues, qualifiers.join(' '), per_page: 1).total_count
+        search_options = { per_page: 1 }
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          qualifiers << 'field.priority-list:Yes'
+          search_options[:advanced_search] = true
+        end
+        client.rest(:search_issues, qualifiers.join(' '), **search_options).total_count
       end
 
       # Submits one or more pre-built payloads to GitHub's "Import Issues" preview endpoint
@@ -663,6 +698,8 @@ 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,
@@ -795,6 +832,16 @@ module PlanMyStuff
       @issue_fields ||= load_issue_fields!
     end
 
+    # @return [Boolean]
+    def priority_list?
+      issue_fields['Priority List'] == 'Yes'
+    end
+
+    # @return [Integer, nil]
+    def priority_list_priority
+      issue_fields['Priority List Priority']
+    end
+
     # Bulk-updates GitHub Issue Field values in a single +setIssueFieldValue+ mutation. Each key is the field display
     # name; values are coerced to the right input fragment based on the field's type. Passing +nil+ as a value clears
     # that field.
@@ -934,6 +981,28 @@ 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,14 +2,16 @@
 
 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_fields; legacy writes forward to set_issue_fields! on save. 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
     attr_accessor :issues_url
-    # @return [Boolean] whether this issue appears on the priority dashboard
-    attr_accessor :priority_list
-    # @return [Integer] sort order on priority dashboard (-1 = unranked)
-    attr_accessor :priority_list_priority
     # @return [Array<Integer>] user IDs of non-support users allowed to view internal comments
     attr_accessor :visibility_allowlist
     # @return [String, nil] merged PR commit SHA for release tracking
@@ -50,8 +52,14 @@ module PlanMyStuff
 
         metadata.responded_at = parse_time(hash[:responded_at])
         metadata.issues_url = hash[:issues_url]
-        metadata.priority_list = hash.fetch(:priority_list, false)
-        metadata.priority_list_priority = hash.fetch(:priority_list_priority, -1)
+        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)
@@ -86,8 +94,6 @@ module PlanMyStuff
 
         metadata.responded_at = nil
         metadata.issues_url = build_issues_url(PlanMyStuff.configuration)
-        metadata.priority_list = false
-        metadata.priority_list_priority = -1
         metadata.visibility_allowlist = []
         metadata.commit_sha = nil
         metadata.auto_complete = true
@@ -169,8 +175,6 @@ module PlanMyStuff
 
     def initialize
       super
-      @priority_list = false
-      @priority_list_priority = -1
       @visibility_allowlist = []
       @auto_complete = true
       @links = []
@@ -188,9 +192,55 @@ 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#update!(issue_fields: { 'Priority List' => 'Yes' })+. 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?
-      !!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#update!(issue_fields: { 'Priority List Priority' => N })+. 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]
@@ -220,8 +270,6 @@ module PlanMyStuff
       super.merge(
         responded_at: PlanMyStuff.format_time(responded_at),
         issues_url: issues_url,
-        priority_list: priority_list,
-        priority_list_priority: priority_list_priority,
         visibility_allowlist: visibility_allowlist,
         commit_sha: commit_sha,
         auto_complete: auto_complete,

data/lib/plan_my_stuff/version.rb

@@ -3,7 +3,7 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 19
+    MINOR = 20
     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.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Brands Insurance