plan_my_stuff 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4ce40c49bbe2d0ef870cf9983a5571631bdcce7f3ce52c31d5cf9885b143e3b
-  data.tar.gz: 8e62775d14932c50fe1b69cf76990345adf697dbdf509603eb7d5b4e35cc982f
+  metadata.gz: 6457257ef431e923519943cd227ffc70488b023467253873e20f52c47fd75f52
+  data.tar.gz: b5a16da4dc6c6c3ce45b307879f5146720f2b878809b7a071b7cc9e33986d210
 SHA512:
-  metadata.gz: cf7fcd9a19a7845293c4b52f69ac7ef0cd9aa966bd0ddeb8851521d842e21f98a6e8ef49996125044bc453d99336ea086852d2d605951d348052a3ce16d2f250
-  data.tar.gz: 9f30fdb98fd6977eeb4362fe41f99472b4771299fa123a080bc83900c65bb794f69f19d5cdb1642efb4867435413ce01169014555641264896b1465b54dc6952
+  metadata.gz: efee5f594d9bd014b0ce575781790768a8d51277010d9ad9902ac11beea06c17d39232d65a77532768326eccece3ebcbe3bdb18c464341c963eda9b12b1d6075
+  data.tar.gz: ef94bc70d08874c2347e243d0f7967ca7bca2e631cda775494a714df6501d22fe5011a09db805dbb53f5fe8397eb32b8bdf19bbf8a235da39d3f5dd4810c011a

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.9.0
+
+### Breaking
+
+- `config.should_send_request` and `config.job_classes` accessors — declared but never wired up. The request gateway that would honor them is deferred (see `requirements/09_request_gateway.md` and `designs/init/gem_mvp_deferred_notes.md`); they will return when the gateway lands
+
+### Added
+
+- `CONFIGURATION.md` is now available bundled with the gem
+
+### Changed
+
+- `config.repos` is now assignable as a whole hash (`config.repos = { atlas: 'Org/Atlas', autofill: 'Org/atlas-autofill-moz' }`) in addition to the existing `config.repos[:key] = '...'` form
+- `Issue.create!` / `Issue.update!` `issue_type:` kwarg now accepts the Symbol nicknames (`'bug'`, `'feature'`, `'it_issue'`, `'other'`, `'performance'`, `'question'`, `'task'`) as Strings too, resolving them to the same canonical name
+
+## 0.8.0
+
+### Breaking
+
+- Issue show "Take" button is now hidden when the issue already has assignees, and `Issues::TakesController#create` rejects the request with a flash error naming the existing assignee. Best-effort race guard for two users clicking Take simultaneously — without it, GitHub silently piles the second user on as a co-assignee.
+  - Guard lives in the controller, not `Pipeline.take!` itself, because webhook paths (`handle_issue_assigned`, `handle_projects_v2_item`, `handle_draft_opened`, `handle_converted_to_draft`) legitimately call `take!` on already-assigned issues
+- `Issue#add_viewers` / `Issue#remove_viewers` renamed to `Issue#add_viewers!` / `Issue#remove_viewers!` for consistency with other mutating instance methods (`approve!`, `close!`, etc.)
+- `Approval#status` extended to a 3-state model (`pending`, `approved`, `rejected`); `Approval` gains a `rejected_at` attribute serialized in `to_h` and the metadata blob. Existing approvals deserialize unchanged (`rejected_at` defaults to `nil`)
+- `Issue#fully_approved?` now requires every approver to be `approved` — a single rejection blocks the gate until revoked. Previously equivalent to `pending_approvals.empty?`, which silently treated rejections as "done"
+- `Issue#revoke_approval!` accepts either an `approved` or `rejected` source state (previously only `approved`); raises `ValidationError` when the target is still `pending`. Authorization error message updated to "another user's response"
+
+### Added
+
+- `CONFIGURATION.md` documents every `PlanMyStuff::Configuration` option grouped by concern; `README.md` Configuration section trimmed to the two required options plus a link
+- Install generator's initializer template now includes the four pipeline options previously missing from it: `pipeline_testing_field_name`, `pipeline_testing_values`, `pipeline_completion_purge_enabled`, `pipeline_completion_ttl_hours`
+- Project show "Remove from project" button (and `DELETE /projects/:project_id/items/:id` route on `ProjectItemsController`) lets the user remove an item from a project board without bouncing out to GitHub. Calls `ProjectItem#destroy!` which fires `plan_my_stuff.project_item.removed`
+- Issue show "Release" button (and `DELETE /issues/:issue_id/take` route on `Issues::TakesController`) lets a dev who took an issue undo their assignment from the same view, without bouncing out to GitHub or the project board. When the current user is the sole assignee the issue's GitHub assignees are cleared and the project item is removed from the pipeline (`project_item.destroy!`); when other assignees remain the current user is unassigned via `project_item.assign!(remaining)` and the item stays on the project
+- `config.import_access_token` classic PAT (requires `repo` scope) used exclusively for the Issues Import API (`golden-comet-preview`); fine-grained tokens are not supported by that endpoint. Optional — defaults to `nil`
+- `Issue.import!(payloads)` POSTs an `Array<Hash>` (one POST per payload) to GitHub's "Import Issues" preview endpoint and returns one status hash per input. Each payload must include `:repo` plus the GitHub-shaped `:issue` / `:comments` keys; payloads are passed through unchanged otherwise
+- `Issue.check_import!(import_id, repo:)` polls a previously-submitted import for its status
+- `Issue#created_at` / `Comment#created_at` attributes hydrated from GitHub's `created_at` field
+- `Issue#issue_type` reader hydrated from GitHub's native `type.name`. `Issue.create!` and `Issue.update!` accept an `issue_type:` kwarg as a String (passed through), Symbol shortcut (`:bug`, `:feature`, `:it_issue`, `:other`, `:performance`, `:question`, `:task`), or `nil`. On `update!`, omitting the kwarg leaves the type untouched; passing `nil` clears it
+- `config.issue_types` Hash{String => String} maps canonical type names to org-specific display names so consuming apps can rename without touching call sites (e.g. `{ 'Feature' => 'Enhancement' }`); missing keys pass through unchanged
+- `config.controller_rescue` Proc invoked from every user-facing controller `rescue` block (after the gem logs the error and stack trace) so consuming apps can forward swallowed errors to their monitoring service
+- `Issue#reject!(user:)` symmetric with `approve!`; accepts either `pending` or `approved` source state and raises `ValidationError` when already rejected. Fires `plan_my_stuff.issue.approval_rejected` and, when the flip drops the issue out of `fully_approved?`, `approvals_invalidated(trigger: :rejected)`
+- `Issue#approve!` now accepts either `pending` or `rejected` source state; raises `ValidationError` only on `approved -> approved`. Clears `rejected_at` on the rejected -> approved transition
+- `Issue#rejected_approvals` reader returns the subset of approvers with `status == 'rejected'`
+- New events: `plan_my_stuff.issue.approval_rejected` and `plan_my_stuff.issue.rejection_revoked` (the latter fires when revoking a rejection back to pending)
+- Approvals partial renders a `Reject` button alongside `Approve` for pending approvers, a `rejected at <ts>` row, a parenthetical rejected count in the header, and a `Revoke` button for either non-pending state
+
 ## 0.7.0
 
 ### Added
@@ -17,7 +62,7 @@
 - `Pipeline.submit!` removed; consuming apps that called it directly should switch to `ProjectItem.create!` + `Pipeline.take!`
 - `Pipeline::Status::SUBMITTED` and `Pipeline::Status::TESTING` constants removed; `Status::ALL` no longer includes them
 - `Pipeline.request_testing!` no longer moves the `Status` field — it now writes to a separate `Testing` single-select custom field on the pipeline project. The pipeline project must have a `Testing` field with `Testing` / `Not testing` options
-- Active pipeline status set is now `Started → In Review → Ready for Release → Release in Progress → Completed`
+- Active pipeline status set is now `Started -> In Review -> Ready for Release -> Release in Progress -> Completed`
 
 ### Added
 

data/CONFIGURATION.md

@@ -0,0 +1,351 @@
+# Configuration
+
+Every PlanMyStuff option lives on `PlanMyStuff::Configuration`. The install generator drops a fully-commented copy at
+`config/initializers/plan_my_stuff.rb` — this file documents the same options grouped by concern. Defaults shown apply
+when the option is left unset.
+
+```ruby
+PMS.configure do |config|
+  # ...
+end
+```
+
+`PMS` is an alias for `PlanMyStuff`; consuming apps can use either.
+
+## Authentication (required)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `access_token` | `String` | — | GitHub PAT with `repo` and `project` scopes. Required. |
+| `import_access_token` | `String, nil` | `nil` | Classic PAT (requires `repo` scope) for the Issues Import API. Fine-grained tokens are not supported by that endpoint. |
+| `organization` | `String` | — | GitHub organization name. Required. |
+
+Both `access_token` and `organization` are validated by `config.validate!`; missing or blank values raise `PlanMyStuff::ConfigurationError`.
+
+> [!NOTE]
+> `import_access_token` is only required if you choose to use `PMS::Issue.import!`/`PMS::Issue.check_import!`
+
+```ruby
+config.access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_token)
+config.import_access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_import_token)
+config.organization = 'YourOrg'
+```
+
+## Repositories
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `repos` | `Hash{Symbol => String}` | `{}` | Named repo configs mapping a key to an `Org/Repo` string. |
+| `default_repo` | `Symbol, nil` | `nil` | Repo key used when callers omit the `repo:` param. |
+
+```ruby
+config.repos = { element: 'YourOrg/Element', underwriter: 'YourOrg/Underwriter' }
+config.default_repo = :element
+```
+
+`repos` can be mutated via `config.repos[:key] = '...'` or set via `config.repos = { key: 'MyOrg/MyRepo' }`
+
+## Projects
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `default_project_number` | `Integer, nil` | `nil` | Default Projects V2 number for `add_to_project: true`. |
+| `testing_template_project_number` | `Integer, nil` | `nil` | Project to clone in `TestingProject.create!` instead of bootstrapping fields. |
+
+```ruby
+config.default_project_number = 14
+config.testing_template_project_number = 42
+```
+
+## App identity
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `app_name` | `String, nil` | `nil` | Stored in metadata so subscribers can attribute writes. |
+| `issues_url_prefix` | `String, nil` | `nil` | Prefix for `Issue#user_link`; the gem appends the issue number. |
+
+```ruby
+config.app_name = 'MyApp'
+
+url_options = Rails.application.config.action_mailer.default_url_options
+config.issues_url_prefix = "#{url_options[:protocol] || 'http'}://#{url_options[:host]}/issues"
+```
+
+## User integration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `user_class` | `String` | `'User'` | Consuming app's user model class name, constantized for lookups. |
+| `display_name_method` | `Symbol` | `:to_s` | Method called on a user to get the display name for comment headers. |
+| `user_id_method` | `Symbol` | `:id` | Method called on a user to extract the app-side user ID. |
+| `support_method` | `Symbol, Proc` | `:support?` | Method name on the user, or a proc receiving the user, returning whether they're support staff. |
+| `github_login_for` | `Hash{Object => String}` | `{}` | Maps app user id (from `user_id_method`) to GitHub login. Powers the Take UI. |
+
+`support_method` may be a method name on the user object or a proc that receives the user and returns boolean.
+`github_login_for` maps app user id (whatever `user_id_method` returns) to GitHub login and powers the Take UI.
+
+```ruby
+config.user_class = 'User'
+config.display_name_method = :full_name
+config.user_id_method = :id
+config.support_method = :support?
+# or: config.support_method = -> (user) { user.role.in?(%w[support admin]) }
+config.github_login_for = {
+  1 => 'some_username',
+  2 => 'octocat',
+}
+```
+
+## Engine authentication
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `authenticate_with` | `Proc` | `nil` | Block executed as a `before_action` on every engine controller. |
+
+```ruby
+config.authenticate_with do
+  redirect_to main_app.login_path unless current_user
+end
+```
+
+## Markdown rendering
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `markdown_renderer` | `Symbol` | `:commonmarker` | Which markdown gem to use: `:commonmarker`, `:redcarpet`, or `nil` (raw HTML-escaped). |
+| `markdown_options` | `Hash` | `{}` | Default options passed to the renderer. Per-call options merge on top of these. |
+
+Set `markdown_renderer` to `:commonmarker`, `:redcarpet`, or `nil` (raw HTML-escaped). The chosen gem must be in your
+Gemfile.
+
+```ruby
+config.markdown_renderer = :commonmarker
+config.markdown_options = { render: { hardbreaks: true } }
+```
+
+## Notification actor
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `current_user` | `Proc, nil` | `nil` | Fallback actor for notification events when `user:` is not passed. |
+
+```ruby
+config.current_user = -> { Current.user }
+```
+
+## Controller rescue
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `controller_rescue` | `Proc, nil` | `nil` | Receives the rescued exception. Forward to your monitoring service. |
+
+```ruby
+config.controller_rescue = -> (error) { MonitoringService.notice_error(error) }
+```
+
+## Custom fields
+
+App-defined fields stored in metadata. Keys are field names; values are hashes with `:type` and `:required`.
+Supported types: `:string`, `:integer`, `:boolean`, `:array`, `:hash`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `custom_fields` | `Hash{Symbol => Hash}` | `{}` | Shared field definitions across all contexts. |
+| `issue_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Issue-only definitions; merged on top of shared. |
+| `comment_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Comment-only definitions; merged on top of shared. |
+| `project_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Project-only definitions; merged on top of shared. |
+| `testing_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Testing-project-only definitions; merged on top of shared. |
+
+Context-specific config wins on key conflicts.
+
+```ruby
+config.custom_fields = {
+  notification_recipients: { type: :array, required: true },
+}
+config.issue_custom_fields = {
+  ticket_type: { type: :string, required: true },
+}
+config.comment_custom_fields = {
+  internal_note: { type: :boolean },
+}
+config.project_custom_fields = {
+  team: { type: :string },
+}
+config.testing_custom_fields = {
+  test_plan_url: { type: :string },
+}
+```
+
+## Issue types
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `issue_types` | `Hash{String => String}` | `{}` | Maps the gem's canonical issue type names to your org's display names. |
+
+Maps the gem's canonical type names (`'Bug'`, `'Feature'`, `'IT Issue / Hardware'`, `'Other'`, `'Performance'`,
+`'Question'`, `'Task'`) to whatever your org uses. Missing keys pass through unchanged.
+
+```ruby
+config.issue_types = {
+  'Bug' => 'User Bug',
+  'Feature' => 'Enhancement',
+}
+```
+
+## Release pipeline
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `pipeline_enabled` | `Boolean` | `true` | Whether the release pipeline feature is enabled. |
+| `pipeline_project_number` | `Integer, nil` | `nil` | Projects V2 number for the pipeline board. Falls back to `default_project_number`. |
+| `webhook_secret` | `String, nil` | `nil` | HMAC secret for GitHub webhook signature verification. Required when webhook routes are mounted. |
+| `pipeline_statuses` | `Hash{String => String}` | `{}` | Display aliases for canonical pipeline status names. |
+| `pipeline_testing_field_name` | `String` | `'Testing'` | Display name for the pipeline project's `Testing` single-select field. |
+| `pipeline_testing_values` | `Hash{Symbol => String}` | `{ active: 'Testing', inactive: 'Not testing' }` | Display labels for the canonical `:active`/`:inactive` testing options. |
+| `pipeline_completion_purge_enabled` | `Boolean` | `true` | Whether the sweep removes aged-out `Completed` items from the pipeline. |
+| `pipeline_completion_ttl_hours` | `Integer` | `24` | Hours after a `Completed` item's last update at which the sweep removes it. |
+| `main_branch` | `String` | `'main'` | Branch PRs merge into for the "Ready for Release" transition. |
+| `production_branch` | `String` | `'production'` | Branch PRs mereg into for the "Release in Progress" transition. |
+
+`pipeline_statuses` aliases the canonical status names (`'Submitted'`, `'Started'`, `'In Review'`, `'Testing'`,
+`'Ready for Release'`, `'Release in Progress'`, `'Completed'`) for display only. The constants remain the internal
+identifiers.
+
+`pipeline_completion_*` controls the sweep that removes aged-out `Completed` items from the pipeline. `webhook_secret`
+is required when webhook routes are mounted.
+
+```ruby
+config.pipeline_enabled = true
+config.pipeline_project_number = 14
+config.webhook_secret = Rails.application.credentials.dig(:plan_my_stuff, :webhook_secret)
+config.pipeline_statuses = {
+  'Submitted' => 'Triaged',
+  'Completed' => 'Done',
+}
+config.pipeline_testing_field_name = 'Testing'
+config.pipeline_testing_values = { active: 'Testing', inactive: 'Not testing' }
+config.pipeline_completion_purge_enabled = true
+config.pipeline_completion_ttl_hours = 24
+config.main_branch = 'main'
+config.production_branch = 'production'
+```
+
+## Follow-up reminders
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `reminders_enabled` | `Boolean` | `true` | Whether the reminders sweep performs any work. |
+| `reminder_days` | `Array<Integer>` | `[1, 3, 7, 10, 14, 18]` | Days-since-waiting at which reminder events fire. |
+| `inactivity_close_days` | `Integer` | `30` | Days of inactivity after which the sweep auto-closes a waiting issue. |
+| `waiting_on_user_label` | `String` | `'waiting-on-user'` | Label flagging issues waiting on an end-user reply. |
+| `waiting_on_approval_label` | `String` | `'waiting-on-approval'` | Label flagging issues waiting on pending approvals. |
+| `user_inactive_label` | `String` | `'user-inactive'` | Label applied to issues auto-closed by the inactivity sweep; removed when an issue is auto-reopened via a user reply. |
+
+Per-issue reminder override: `issue.metadata.reminder_days = [...]`.
+
+```ruby
+config.reminders_enabled = true
+config.reminder_days = [1, 3, 7, 10, 14, 18]
+config.inactivity_close_days = 30
+config.waiting_on_user_label = 'waiting-on-user'
+config.waiting_on_approval_label = 'waiting-on-approval'
+config.user_inactive_label = 'user-inactive'
+```
+
+## Auto-archiving
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `archiving_enabled` | `Boolean` | `true` | Whether the archive sweep performs any work. |
+| `archive_closed_after_days` | `Integer` | `90` | Days after `closed_at` at which a non-inactive-closed issue becomes an archive candidate. |
+| `archived_label` | `String` | `'archived'` | Label added to archived issues; also used by the sweep as a skip marker. |
+
+The archive sweep piggybacks `RemindersSweepJob`. Inactivity-closed and non-PMS issues are excluded.
+
+```ruby
+config.archiving_enabled = true
+config.archive_closed_after_days = 90
+config.archived_label = 'archived'
+```
+
+## AWS webhook
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `sns_topic_arn` | `String, nil` | `nil` | Expected SNS topic ARN for AWS webhook validation. |
+| `aws_service_identifier` | `String, nil` | `nil` | Suffix matched against ECS event resource ARNs (e.g. `'my-app-production-2-web-server'`). |
+| `production_commit_sha` | `String, nil` | `nil` | Prefix-matched against issue metadata `commit_sha` on `SERVICE_DEPLOYMENT_COMPLETED` events. |
+| `process_aws_webhooks` | `Boolean` | `Rails.env.production?` | Whether to process incoming AWS webhook events. |
+| `sns_verifier_class` | `Class` | `Aws::SNS::MessageVerifier` (when defined) | Class instantiated per request for SNS signature verification. Must respond to `authenticate!(raw_body)`. |
+| `sns_verifier_error` | `Class` | `Aws::SNS::MessageVerifier::VerificationError` (when defined) | Exception class rescued during SNS signature verification. |
+
+`production_commit_sha` is prefix-matched against issue metadata `commit_sha` on `SERVICE_DEPLOYMENT_COMPLETED` events.
+`sns_verifier_class` must respond to `authenticate!(raw_body)`.
+
+```ruby
+config.sns_topic_arn = 'arn:aws:sns:us-east-1:123456:ecs-deploy-topic'
+config.aws_service_identifier = 'myapp-production-web'
+config.production_commit_sha = Rails.configuration.x.image_tag
+config.process_aws_webhooks = Rails.env.production?
+config.sns_verifier_class = Aws::SNS::MessageVerifier
+config.sns_verifier_error = Aws::SNS::MessageVerifier::VerificationError
+```
+
+## Caching
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cache_enabled` | `Boolean` | `true` | ETag-based HTTP caching of GitHub reads via `Rails.cache`. |
+| `cache_version` | `String, nil` | `nil` | Opaque string baked into every PMS cache key; bump to invalidate. |
+
+```ruby
+config.cache_enabled = true
+config.cache_version = Rails.configuration.x.image_tag
+```
+
+## Route mounting
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mount_groups` | `Hash{Symbol => Boolean}` | `{ webhooks: true, issues: true, projects: true }` | Per-group route mounting toggles. Set a key to `false` to skip mounting that group. |
+
+```ruby
+config.mount_groups = { webhooks: true, issues: true, projects: true }
+```
+
+## Controller overrides
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `controllers` | `Hash{Symbol => String}` | `{}` | Per-route controller overrides. Keys are controllable route symbols; values are fully-qualified controller paths. |
+
+Per-route controller overrides. Keys are the controllable route symbols defined in
+`PlanMyStuff::Configuration::DEFAULT_CONTROLLERS`; values are fully-qualified controller paths. Unset keys fall back to
+the gem default.
+
+```ruby
+config.controllers[:issues] = 'my_app/issues'
+```
+
+Controllable keys (with gem defaults):
+
+| Key | Default |
+|---|---|
+| `:issues` | `plan_my_stuff/issues` |
+| `:comments` | `plan_my_stuff/comments` |
+| `:labels` | `plan_my_stuff/labels` |
+| `:projects` | `plan_my_stuff/projects` |
+| `:project_items` | `plan_my_stuff/project_items` |
+| `:testing_projects` | `plan_my_stuff/testing_projects` |
+| `:testing_project_items` | `plan_my_stuff/testing_project_items` |
+| `:'issues/closures'` | `plan_my_stuff/issues/closures` |
+| `:'issues/viewers'` | `plan_my_stuff/issues/viewers` |
+| `:'issues/takes'` | `plan_my_stuff/issues/takes` |
+| `:'issues/waitings'` | `plan_my_stuff/issues/waitings` |
+| `:'issues/links'` | `plan_my_stuff/issues/links` |
+| `:'issues/approvals'` | `plan_my_stuff/issues/approvals` |
+| `:'project_items/statuses'` | `plan_my_stuff/project_items/statuses` |
+| `:'project_items/assignments'` | `plan_my_stuff/project_items/assignments` |
+| `:'testing_project_items/results'` | `plan_my_stuff/testing_project_items/results` |
+| `:'webhooks/github'` | `plan_my_stuff/webhooks/github` |
+| `:'webhooks/aws'` | `plan_my_stuff/webhooks/aws` |