plan_my_stuff 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bded03d75c7bd996c62c647b038a588a4286628e7f041e385d4464ea87955505
-  data.tar.gz: 5b778d271d85a1ad5681d8617dec41875d5664d0c3ea861ab9421bef962de4d2
+  metadata.gz: 06744d7c7bc63206522ce6d7c9176eeb8e93fabb4de903d7df32b17cfae6948d
+  data.tar.gz: 2338f2f85989b2ee3b29a48c114a82d36c8105c13e4caf19b2601ff02cbf063c
 SHA512:
-  metadata.gz: db446cfa7623c4091f67cecd89ab7dfe84207237e601fd53f4a73401fc02d2019072801c326d281febb54373817cb87d35c60e2929a2ec425f1aca3e7623ef49
-  data.tar.gz: b7f4328f697271829202ee201f4c05a9e1553bc95d50b721cfc3132462c0401428b87e22bd79cdeb4962e249bea991b3f5d39cab9cb1a3c048ef13a647e31312
+  metadata.gz: dd143db048f77a46fe7875b1592b9ff1dc26e6ddac13af60c177ae977f799606d172a23ca861222a1a133d53fb91d16be19dd40d8f7027b680316276d99088f0
+  data.tar.gz: 607957cf66e887c31bb6ab3f9a93726da0cf853cb3d43e8d34857b0dd789981788de4f0c8c6e076ad5236141732867ed9641971dcc683df5e4683e6b726542f3

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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
+
+- Every controller action now yields its primary object to a block when subclassed, so consumers can do
+  `super do |obj| ... end` to wedge in audit-log / instrumentation without rewriting the action. Webhook
+  controllers yield `(payload, result)`. See [CONFIGURATION.md](CONFIGURATION.md).
+
 ## 0.18.0
 
 ### Breaking

data/CONFIGURATION.md

@@ -374,6 +374,54 @@ Controllable keys (with gem defaults):
 | `:'webhooks/github'` | `plan_my_stuff/webhooks/github` |
 | `:'webhooks/aws'` | `plan_my_stuff/webhooks/aws` |
 
+### Customizing per-action behavior
+
+Every mounted route resolves its controller through `config.controller_for(key)`. Subclass a gem controller in your
+own app and register it to wedge in `before_action`s, authentication, or response tweaks - no monkey patching:
+
+```ruby
+# app/controllers/my_app/issues_controller.rb
+class MyApp::IssuesController < PMS::IssuesController
+  before_action :authenticate_user!
+  before_action :authorize_ticket_access
+end
+```
+
+```ruby
+# config/initializers/plan_my_stuff.rb
+PlanMyStuff.configure do |config|
+  config.controllers[:issues] = 'my_app/issues'
+end
+```
+
+For per-action side effects (audit log, metrics, notifications) without rewriting the action, yielding actions
+pass their primary object to an optional block on the happy path. Call `super do |obj| ... end` from a subclass:
+
+```ruby
+class MyApp::IssuesController < PMS::IssuesController
+  def create
+    super do |issue|
+      AuditLog.record(actor: current_user, action: :issue_created, target: issue)
+    end
+  end
+
+  def update
+    super do |issue|
+      AuditLog.record(actor: current_user, action: :issue_updated, target: issue)
+    end
+  end
+end
+```
+
+Contract:
+
+- The yield fires on the happy path, after the model load / write succeeds and before the gem's default
+  `flash[:success]` + `redirect_to`. Error branches, `not_found`, and authorization redirects do not yield.
+- Read actions (`index`, `show`, `new`, `edit`) yield before the implicit render; `index` yields the collection,
+  the rest yield the single object.
+- If your block calls `render` or `redirect_to`, the gem's default response is skipped (the action checks
+  `performed?`), so you can fully replace the response from the block.
+
 ### Parent controller
 
 | Option | Type | Default | Description |

data/README.md

@@ -787,34 +787,6 @@ All routes are under the engine's mount point. Each group can be disabled via `c
 
 ## Controller overrides
 
-Every mounted route resolves its controller through `config.controller_for(key)`, which looks up `config.controllers[key]` and falls back to the gem default. Subclass a gem controller in your own app and register it to wedge in before_actions, authentication, or response tweaks — no monkey patching.
-
-```ruby
-# app/controllers/my_app/issues_controller.rb
-class MyApp::IssuesController < PMS::IssuesController
-  before_action :authenticate_user!
-  before_action :authorize_ticket_access
-end
-```
-
-```ruby
-# config/initializers/plan_my_stuff.rb
-PlanMyStuff.configure do |config|
-  config.controllers['issues'] = 'my_app/issues'
-end
-```
-
-Overridable keys (see `PMS::Configuration::DEFAULT_CONTROLLERS`):
-
-```text
-issues                         issues/closures
-comments                       issues/viewers
-labels                         issues/takes
-projects                       issues/waitings
-project_items                  issues/links
-testing_projects               issues/approvals
-testing_project_items          project_items/statuses
-webhooks/github                project_items/assignments
-webhooks/aws                   testing_project_items/results
-```
+See [CONFIGURATION.md](CONFIGURATION.md#controller-overrides) for the full walkthrough including subclassing,
+per-route registration, and the per-action block hook.
 

data/app/controllers/plan_my_stuff/comments_controller.rb

@@ -6,7 +6,7 @@ module PlanMyStuff
     def create
       @issue = PlanMyStuff::Issue.find(params[:issue_id])
 
-      PlanMyStuff::Comment.create!(
+      comment = PlanMyStuff::Comment.create!(
         issue: @issue,
         body: comment_params[:body],
         user: pms_current_user,
@@ -14,6 +14,9 @@ module PlanMyStuff
         waiting_on_reply: comment_params[:waiting_on_reply] == '1',
       )
 
+      yield(comment) if block_given?
+      return if performed?
+
       flash[:success] = 'Comment was successfully created.'
       redirect_to(plan_my_stuff.issue_path(@issue))
     rescue PlanMyStuff::LockedIssueError => e
@@ -27,9 +30,14 @@ module PlanMyStuff
       load_comment
       return unless @comment
       return redirect_to_issue if issue_body_comment?
-      return if can_edit?(@comment)
 
-      redirect_to_unauthorized(plan_my_stuff.issue_path(@issue))
+      unless can_edit?(@comment)
+        redirect_to_unauthorized(plan_my_stuff.issue_path(@issue))
+
+        return
+      end
+
+      yield(@comment) if block_given?
     end
 
     # PATCH/PUT /issues/:issue_id/comments/:id
@@ -49,6 +57,9 @@ module PlanMyStuff
 
       @comment.update!(**update_attrs, user: pms_current_user)
 
+      yield(@comment) if block_given?
+      return if performed?
+
       flash[:success] = 'Comment was successfully updated.'
       redirect_to(plan_my_stuff.issue_path(@issue))
     rescue PlanMyStuff::StaleObjectError => e

data/app/controllers/plan_my_stuff/issues/approvals_controller.rb

@@ -26,6 +26,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.request_approvals!(user_ids: user_ids, user: pms_current_user)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Approvers were successfully added.'
         redirect_to(show_path)
       rescue PlanMyStuff::AuthorizationError, PlanMyStuff::ValidationError => e
@@ -71,6 +74,9 @@ module PlanMyStuff
           flash[:success] = 'Response revoked.'
         end
 
+        yield(issue) if block_given?
+        return if performed?
+
         redirect_to(show_path)
       rescue PlanMyStuff::AuthorizationError, PlanMyStuff::ValidationError => e
         pms_handle_rescue(e)
@@ -88,6 +94,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.remove_approvers!(user_ids: [params[:id].to_i], user: pms_current_user)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Approver was successfully removed.'
         redirect_to(show_path)
       rescue PlanMyStuff::AuthorizationError, PlanMyStuff::ValidationError => e

data/app/controllers/plan_my_stuff/issues/closures_controller.rb

@@ -14,6 +14,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.update!(state: :closed)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Issue was successfully closed.'
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::Error, ArgumentError => e
@@ -27,6 +30,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.update!(state: :open)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Issue was successfully reopened.'
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::Error, ArgumentError => e

data/app/controllers/plan_my_stuff/issues/links_controller.rb

@@ -28,6 +28,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         link = add_link(issue, type)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = "Linked #{link}"
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::ValidationError, ActiveModel::ValidationError, ArgumentError => e
@@ -47,6 +50,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         remove_link(issue, type, repo: repo, number: number)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = "Unlinked #{repo}##{number}"
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::ValidationError, ActiveModel::ValidationError, ArgumentError => e

data/app/controllers/plan_my_stuff/issues/takes_controller.rb

@@ -19,6 +19,10 @@ module PlanMyStuff
 
         PlanMyStuff::Pipeline.take!(project_item)
         assign_current_user(project_item)
+
+        yield(project_item) if block_given?
+        return if performed?
+
         flash[:success] ||= "Issue ##{issue.number} taken."
 
         redirect_to(plan_my_stuff.issue_path(issue))
@@ -48,6 +52,10 @@ module PlanMyStuff
           issue.update!(assignees: remaining)
         end
 
+        yielded = project_item.presence || issue
+        yield(yielded) if block_given?
+        return if performed?
+
         flash[:success] = "Issue ##{issue.number} released."
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue ArgumentError, PlanMyStuff::Error => e

data/app/controllers/plan_my_stuff/issues/viewers_controller.rb

@@ -26,6 +26,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.add_viewers!(user_ids: viewer_ids, user: pms_current_user)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Viewers were successfully added.'
         redirect_to(plan_my_stuff.edit_issue_path(params[:issue_id]))
       rescue PlanMyStuff::Error, Octokit::Error => e
@@ -44,6 +47,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.remove_viewers!(user_ids: [params[:id].to_i], user: pms_current_user)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Viewer was successfully removed.'
         redirect_to(plan_my_stuff.edit_issue_path(params[:issue_id]))
       rescue PlanMyStuff::Error, Octokit::Error => e

data/app/controllers/plan_my_stuff/issues/waitings_controller.rb

@@ -19,6 +19,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.enter_waiting_on_user!(user: pms_current_user)
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Issue marked as waiting on user reply.'
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::Error, ArgumentError => e
@@ -37,6 +40,9 @@ module PlanMyStuff
         issue = PlanMyStuff::Issue.find(params[:issue_id])
         issue.clear_waiting_on_user!
 
+        yield(issue) if block_given?
+        return if performed?
+
         flash[:success] = 'Waiting-on-user state cleared.'
         redirect_to(plan_my_stuff.issue_path(issue))
       rescue PlanMyStuff::Error, ArgumentError => e

data/app/controllers/plan_my_stuff/issues_controller.rb

@@ -17,11 +17,15 @@ module PlanMyStuff
         page: @page,
         per_page: @per_page,
       )
+
+      yield(@issues) if block_given?
     end
 
     # GET /issues/new
     def new
       @issue = PlanMyStuff::Issue.new
+
+      yield(@issue) if block_given?
     end
 
     # POST /issues
@@ -33,6 +37,9 @@ module PlanMyStuff
         user: pms_current_user,
       )
 
+      yield(@issue) if block_given?
+      return if performed?
+
       flash[:success] = 'Issue was successfully created.'
       redirect_to(plan_my_stuff.issue_path(@issue))
     rescue PlanMyStuff::ValidationError => e
@@ -50,11 +57,15 @@ module PlanMyStuff
       @current_user_login = PlanMyStuff.configuration.github_login_for[@current_user_id]
       @pipeline_enabled = PlanMyStuff.configuration.pipeline_enabled
       @pipeline_item = load_pipeline_item(@issue.number) if @pipeline_enabled
+
+      yield(@issue) if block_given?
     end
 
     # GET /issues/:id/edit
     def edit
       @issue = PlanMyStuff::Issue.find(params[:id])
+
+      yield(@issue) if block_given?
     end
 
     # PATCH/PUT /issues/:id
@@ -67,6 +78,9 @@ module PlanMyStuff
         labels: parse_labels(issue_params[:labels]),
       )
 
+      yield(@issue) if block_given?
+      return if performed?
+
       flash[:success] = 'Issue was successfully updated.'
       redirect_to(plan_my_stuff.issue_path(@issue))
     rescue PlanMyStuff::StaleObjectError => e

data/app/controllers/plan_my_stuff/labels_controller.rb

@@ -22,6 +22,9 @@ module PlanMyStuff
 
       PlanMyStuff::Label.add!(issue: issue, labels: labels)
 
+      yield(issue) if block_given?
+      return if performed?
+
       flash[:success] = 'Label was successfully added.'
       redirect_to(plan_my_stuff.issue_path(issue))
     rescue PlanMyStuff::Error, Octokit::Error => e
@@ -35,6 +38,9 @@ module PlanMyStuff
       issue = PlanMyStuff::Issue.find(params[:issue_id])
       PlanMyStuff::Label.remove!(issue: issue, labels: [params[:id]])
 
+      yield(issue) if block_given?
+      return if performed?
+
       flash[:success] = 'Label was successfully removed.'
       redirect_to(plan_my_stuff.issue_path(issue))
     rescue PlanMyStuff::Error, Octokit::Error => e

data/app/controllers/plan_my_stuff/project_items/assignments_controller.rb

@@ -16,6 +16,9 @@ module PlanMyStuff
 
         item.assign!(assignees)
 
+        yield(item) if block_given?
+        return if performed?
+
         flash[:success] =
           if assignees.present?
             "Item assigned to #{assignees.join(', ')}."
@@ -43,6 +46,9 @@ module PlanMyStuff
 
         item.assign!(remaining)
 
+        yield(item) if block_given?
+        return if performed?
+
         flash[:success] = "#{params[:username]} unassigned."
         redirect_to(plan_my_stuff.project_path(params[:project_id]))
       rescue ArgumentError, PlanMyStuff::Error => e

data/app/controllers/plan_my_stuff/project_items/statuses_controller.rb

@@ -14,6 +14,9 @@ module PlanMyStuff
 
         item.move_to!(params[:status])
 
+        yield(item) if block_given?
+        return if performed?
+
         flash[:success] = "Item moved to #{params[:status]}."
         redirect_to(plan_my_stuff.project_path(params[:project_id]))
       rescue ArgumentError, PlanMyStuff::Error => e

data/app/controllers/plan_my_stuff/project_items_controller.rb

@@ -7,19 +7,23 @@ module PlanMyStuff
       project_number = params[:project_id].to_i
 
       if params[:draft] == '1'
-        PlanMyStuff::ProjectItem.create!(
+        item = PlanMyStuff::ProjectItem.create!(
           params[:title],
           draft: true,
           body: params[:body],
           project_number: project_number,
         )
-        flash[:success] = 'Draft item created.'
+        flash_message = 'Draft item created.'
       else
         issue = PlanMyStuff::Issue.find(params[:issue_number].to_i)
-        PlanMyStuff::ProjectItem.create!(issue, project_number: project_number)
-        flash[:success] = "Issue ##{issue.number} added to project."
+        item = PlanMyStuff::ProjectItem.create!(issue, project_number: project_number)
+        flash_message = "Issue ##{issue.number} added to project."
       end
 
+      yield(item) if block_given?
+      return if performed?
+
+      flash[:success] = flash_message
       redirect_to(plan_my_stuff.project_path(project_number))
     rescue ArgumentError, PlanMyStuff::Error, Octokit::Error => e
       pms_handle_rescue(e)
@@ -38,6 +42,9 @@ module PlanMyStuff
 
       item.destroy!(user: pms_current_user)
 
+      yield(item) if block_given?
+      return if performed?
+
       flash[:success] = 'Item removed from project.'
       redirect_to(plan_my_stuff.project_path(project_number))
     rescue ArgumentError, PlanMyStuff::Error, Octokit::Error => e

data/app/controllers/plan_my_stuff/projects_controller.rb

@@ -12,11 +12,15 @@ module PlanMyStuff
         when 'regular' then all_projects.reject { |p| p.is_a?(PlanMyStuff::TestingProject) }
         else all_projects
         end
+
+      yield(@projects) if block_given?
     end
 
     # GET /projects/new
     def new
       @project = PlanMyStuff::Project.new
+
+      yield(@project) if block_given?
     end
 
     # POST /projects
@@ -28,6 +32,9 @@ module PlanMyStuff
         user: pms_current_user,
       )
 
+      yield(@project) if block_given?
+      return if performed?
+
       flash[:success] = 'Project was successfully created.'
       redirect_to(plan_my_stuff.project_path(@project.number))
     rescue PlanMyStuff::ValidationError => e
@@ -46,11 +53,15 @@ module PlanMyStuff
       @project = PlanMyStuff::Project.find(params[:id].to_i)
       @statuses = @project.statuses.pluck(:name)
       @items_by_status = @project.items.group_by(&:status)
+
+      yield(@project) if block_given?
     end
 
     # GET /projects/:id/edit
     def edit
       @project = PlanMyStuff::Project.find(params[:id].to_i)
+
+      yield(@project) if block_given?
     end
 
     # PATCH/PUT /projects/:id
@@ -63,6 +74,9 @@ module PlanMyStuff
         description: project_params[:description],
       )
 
+      yield(@project) if block_given?
+      return if performed?
+
       flash[:success] = 'Project was successfully updated.'
       redirect_to(plan_my_stuff.project_path(@project.number))
     rescue PlanMyStuff::StaleObjectError => e

data/app/controllers/plan_my_stuff/testing_project_items/results_controller.rb

@@ -30,6 +30,9 @@ module PlanMyStuff
           raise(ArgumentError, "Invalid result: #{params[:result].inspect}")
         end
 
+        yield(item) if block_given?
+        return if performed?
+
         redirect_to(plan_my_stuff.testing_project_path(project_number))
       rescue PlanMyStuff::ValidationError => e
         pms_handle_rescue(e)

data/app/controllers/plan_my_stuff/testing_project_items_controller.rb

@@ -5,6 +5,8 @@ module PlanMyStuff
     # GET /testing_projects/:testing_project_id/items/new
     def new
       @project = PlanMyStuff::TestingProject.find(params[:testing_project_id].to_i)
+
+      yield(@project) if block_given?
     rescue PlanMyStuff::Error, Octokit::Error => e
       pms_handle_rescue(e)
       flash[:error] = e.message
@@ -26,6 +28,9 @@ module PlanMyStuff
       item.update_due_date!(Date.parse(item_params[:due_date])) if item_params[:due_date].present?
       item.update_pass_mode!(item_params[:pass_mode]) if item_params[:pass_mode].present?
 
+      yield(item) if block_given?
+      return if performed?
+
       flash[:success] = 'Item added.'
       redirect_to(plan_my_stuff.testing_project_path(project_number))
     rescue ArgumentError, PlanMyStuff::Error, Octokit::Error => e

data/app/controllers/plan_my_stuff/testing_projects_controller.rb

@@ -6,6 +6,8 @@ module PlanMyStuff
     def new
       @project = PlanMyStuff::TestingProject.new
       @project.metadata.subject_urls = [params[:subject_url]] if params[:subject_url].present?
+
+      yield(@project) if block_given?
     end
 
     # POST /testing_projects
@@ -19,6 +21,9 @@ module PlanMyStuff
         user: pms_current_user,
       )
 
+      yield(@project) if block_given?
+      return if performed?
+
       flash[:success] = 'Testing project was successfully created.'
       redirect_to(plan_my_stuff.testing_project_path(@project.number))
     rescue PlanMyStuff::ValidationError => e
@@ -39,11 +44,15 @@ module PlanMyStuff
       @project = PlanMyStuff::TestingProject.find(params[:id].to_i)
       @statuses = @project.statuses.pluck(:name)
       @items_by_status = @project.items.group_by(&:status)
+
+      yield(@project) if block_given?
     end
 
     # GET /testing_projects/:id/edit
     def edit
       @project = PlanMyStuff::TestingProject.find(params[:id].to_i)
+
+      yield(@project) if block_given?
     end
 
     # PATCH/PUT /testing_projects/:id
@@ -60,6 +69,9 @@ module PlanMyStuff
         },
       )
 
+      yield(@project) if block_given?
+      return if performed?
+
       flash[:success] = 'Testing project was successfully updated.'
       redirect_to(plan_my_stuff.testing_project_path(@project.number))
     rescue PlanMyStuff::StaleObjectError => e

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 = 18
+    MINOR = 20
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Brands Insurance
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails