gitlab-triage 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 587e71e912b7d8906ecbc081b1a07258aa6cfe80643ea34c38314256a97ab503
-  data.tar.gz: a83dc6d31326079c8315d24af259d9015c13bb2d759684831633fd295dd0b8a1
+  metadata.gz: 636a4953fea53e7808b154e352c37d6a33c3cd9a57695f98d05fa90a44efd2cc
+  data.tar.gz: 82d61352bdd126d09650ed9f0efcbf1714783444f172a559571d33530000bef2
 SHA512:
-  metadata.gz: ec66a05c1d691deb9eab031e69062762e492301a09fe27e2c3bf85f876b36459d715d2e6c82b6dd39706e568171643316a7558046347d07bb034740d5e0a4d32
-  data.tar.gz: '0359fe4894503d53ba358687b66854d9153a53177ba04ebbadb9106d6d824ae0ad1bc3c2d570834b3ed81cb3ca90f2dd67555c3758ae7e254e1ca8555a825aa8'
+  metadata.gz: '069d55c96a5fac0989ced21614782c06b11ef8a56fb59e7bc457e73fa9bb77c223680ee1399f4854bc22697075880ef3233575a1a332ab75b934664a2a654d44'
+  data.tar.gz: 1521bc67e168f19d231112782f9d12457a422b93e86cfa10a4565eebb026bdbfb8e6401764ecb84a25bbbfe3687f7c189323e106de4ad2b6020618f75dde99fb

data/README.md

@@ -6,9 +6,11 @@ This project contains the library and pipeline definition to enable automated tr
 
 ## gitlab-triage gem
 
-### Summary
+### Abstract
 
-The `gitlab-triage` gem aims to enable project managers and maintainers to automatically triage Issues and Merge Requests in GitLab projects based on defined policies.
+The `gitlab-triage` gem aims to enable project managers and maintainers to
+automatically triage Issues and Merge Requests in GitLab projects based on
+defined policies.
 
 ### What is a triage policy?
 
@@ -16,14 +18,21 @@ Triage policies are defined on a resource level basis, resources being:
 - Issues
 - Merge Requests
 
-Each policy can declare a number of conditions that must all be satisfied before a number of actions are carried out.
+Each policy can declare a number of conditions that must all be satisfied before
+a number of actions are carried out.
+
+Summary policies are special policies that join multiple policies together to
+create a summary issue with all the sub-policies' summaries, see
+[Summary policies](#summary-policies).
 
 ### Defining a policy
 
 Policies are defined in a policy file (by default `./.triage-policies.yml`).
 The format of the file is [YAML](https://en.wikipedia.org/wiki/YAML).
 
-> Note: You can use the [`--init`](#usage) option to add an example [`.triage-policies.yml` file](support/.triage-policies.example.yml) to your project
+> Note: You can use the [`--init`](#usage) option to add an example
+[`.triage-policies.yml` file](support/.triage-policies.example.yml) to your
+project.
 
 Select which resource to add the policy to:
 - `issues`
@@ -602,11 +611,11 @@ Generates an issue summarizing what was triaged.
 
 Accepts a hash of fields.
 
-| Field     | Type   | Description                            | Required | Placeholders | Ruby expression |
-| ----      | ----   | ----                                   | ----     | ----         | ----            |
-| `title`   | string | The title of the generated issue       | yes      | no           | no              |
+| Field     | Type   | Description                                 | Required | Placeholders | Ruby expression |
+| ----      | ----   | ----                                        | ----     | ----         | ----            |
+| `title`   | string | The title of the generated issue            | yes      | no           | no              |
 | `item`    | string | Template representing each triaged resource | no       | yes          | yes             |
-| `summary` | string | The description of the generated issue | no       | Only `{{items}}` and `{{title}}` | yes |
+| `summary` | string | The description of the generated issue      | no       | Only `{{items}}` and `{{title}}` | yes |
 
 **Note:**: Both `item` and `summary` fields act like a
 [comment action](#comment-action), therefore
@@ -658,6 +667,86 @@ Which could generate an issue like:
   /label ~"needs attention"
   ```
 
+### Summary policies
+
+Summary policies are special policies that join multiple rule policies together
+to create a summary issue with all the sub-policies' summaries.
+They have the same structure as Rule policies that define `actions.summarize`.
+
+One key difference is that the `{{items}}` placeholder represents the array of
+sub-policies' summary.
+
+Note that only the `item` and `summary` keys in the sub-policies' `actions` are
+used. Any other keys (e.g. `mention`, `comment`, `labels` etc.) are ignored.
+
+You can define such policy as follows:
+
+```yml
+resource_rules:
+  issues:
+    summaries:
+      - name: Newest and oldest issues summary
+        actions:
+          summarize:
+            title: "Newest and oldest issues summary"
+            summary: |
+              Please triage the following issues:
+
+              {{items}}
+
+              Please take care of them before the end of #{7.days.from_now.strftime('%Y-%m-%d')}
+
+              /label ~"needs attention"
+        rules:
+          - name: New issues
+            conditions:
+              state: opened
+            limits:
+              most_recent: 2
+            actions:
+              item: "- [ ] [{{title}}]({{web_url}}) {{labels}}"
+              summary: |
+                Please triage the following new issues:
+
+                {{items}}
+          - name: Old issues
+            conditions:
+              state: opened
+            limits:
+              oldest: 2
+            actions:
+              item: "- [ ] [{{title}}]({{web_url}}) {{labels}}"
+              summary: |
+                Please triage the following old issues:
+
+                {{items}}
+```
+
+Which could generate an issue like:
+
+* Title:
+  ```
+  Newest and oldest issues summary
+  ```
+* Description:
+  ``` markdown
+  Please triage the following issues:
+
+  Please triage the following new issues:
+
+  - [ ] [A new issue](http://example.com/group/project/issues/4)
+  - [ ] [Another new issue](http://example.com/group/project/issues/3) ~"label B", ~"label C"
+
+  Please triage the following old issues:
+
+  - [ ] [An old issue](http://example.com/group/project/issues/1) ~"label A", ~"label B"
+  - [ ] [Another old issue](http://example.com/group/project/issues/2) ~"label C"
+
+  Please take care of them before the end of 2000-01-01
+
+  /label ~"needs attention"
+  ```
+
 ### Ruby expression API
 
 Here's a list of currently available Ruby expression API:
@@ -741,11 +830,13 @@ run:triage:triage:
 Yes, you can override the host url using the following options:
 
 ##### CLI
+
 ```
 gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/triage --host-url https://gitlab.host.com
 ```
 
 ##### Policy file
+
 ```yml
 host_url: https://gitlab.host.com
 resource_rules:
@@ -753,4 +844,4 @@ resource_rules:
 
 ### Contributing
 
-Please refer to the [Contributing Guide](CONTRIBUTING.md)
+Please refer to the [Contributing Guide](CONTRIBUTING.md).

data/lib/gitlab/triage/action.rb

@@ -4,15 +4,12 @@ require_relative 'action/comment'
 module Gitlab
   module Triage
     module Action
-      def self.process(rules:, **args)
-        summarize = rules.delete(:summarize)
-        comment = rules.any? && rules
-
+      def self.process(policy:, **args)
         {
-          Summarize => summarize,
-          Comment => comment
-        }.compact.each do |action, rule|
-          act(action: action, rule: rule, **args) if rule
+          Summarize => policy.summarize?,
+          Comment => policy.comment?
+        }.compact.each do |action, active|
+          act(action: action, policy: policy, **args) if active
         end
       end
 

data/lib/gitlab/triage/action/base.rb

@@ -2,13 +2,10 @@ module Gitlab
   module Triage
     module Action
       class Base
-        attr_reader :name, :type, :rule, :resources, :net
+        attr_reader :policy, :net
 
-        def initialize(name:, type:, rule:, resources:, net:)
-          @name = name
-          @type = type
-          @rule = rule
-          @resources = resources
+        def initialize(policy:, net:)
+          @policy = policy
           @net = net
         end
       end

data/lib/gitlab/triage/action/comment.rb

@@ -14,7 +14,7 @@ module Gitlab
       class Comment < Base
         class Dry < Comment
           def act
-            puts "\nThe following comments would be posted for the rule **#{name}**:\n\n"
+            puts "The following comments would be posted for the rule **#{policy.name}**:\n\n"
 
             super
           end
@@ -27,7 +27,7 @@ module Gitlab
         end
 
         def act
-          resources.each do |resource|
+          policy.resources.each do |resource|
             comment = build_comment(resource).strip
 
             perform(resource, comment) unless comment.empty?
@@ -39,11 +39,11 @@ module Gitlab
         def build_comment(resource)
           CommandBuilders::CommentCommandBuilder.new(
             [
-              CommandBuilders::TextContentBuilder.new(rule[:comment], resource: resource, net: net).build_command,
-              CommandBuilders::LabelCommandBuilder.new(rule[:labels]).build_command,
-              CommandBuilders::RemoveLabelCommandBuilder.new(rule[:remove_labels]).build_command,
-              CommandBuilders::CcCommandBuilder.new(rule[:mention]).build_command,
-              CommandBuilders::StatusCommandBuilder.new(rule[:status]).build_command
+              CommandBuilders::TextContentBuilder.new(policy.actions[:comment], resource: resource, net: net).build_command,
+              CommandBuilders::LabelCommandBuilder.new(policy.actions[:labels]).build_command,
+              CommandBuilders::RemoveLabelCommandBuilder.new(policy.actions[:remove_labels]).build_command,
+              CommandBuilders::CcCommandBuilder.new(policy.actions[:mention]).build_command,
+              CommandBuilders::StatusCommandBuilder.new(policy.actions[:status]).build_command
             ]
           ).build_command
         end
@@ -61,7 +61,7 @@ module Gitlab
             host_url: net[:host_url],
             api_version: net[:api_version],
             source_id: net[:source_id],
-            resource_type: type,
+            resource_type: policy.type,
             resource_id: resource['iid'],
             sub_resource_type: 'notes'
           ).build

data/lib/gitlab/triage/action/summarize.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative 'summarize/issue_builder'
 
 module Gitlab
   module Triage
@@ -11,7 +10,7 @@ module Gitlab
           private
 
           def perform
-            puts "\nThe following issue would be created for the rule **#{name}**:\n\n"
+            puts "The following issue would be created for the rule **#{policy.name}**:\n\n"
             puts ">>>"
             puts "* Title: #{issue.title}"
             puts "* Description: #{issue.description}"
@@ -20,7 +19,7 @@ module Gitlab
         end
 
         def act
-          perform if resources.any? && issue.valid?
+          perform if policy.resources.any? && issue.valid?
         end
 
         private
@@ -30,7 +29,7 @@ module Gitlab
         end
 
         def issue
-          @issue ||= IssueBuilder.new(rule, resources, net)
+          @issue ||= policy.build_issue
         end
 
         def post_issue_url

data/lib/gitlab/triage/engine.rb

@@ -10,6 +10,8 @@ require_relative 'filters/assignee_member_conditions_filter'
 require_relative 'filters/ruby_conditions_filter'
 require_relative 'limiters/date_field_limiter'
 require_relative 'action'
+require_relative 'policies/rule_policy'
+require_relative 'policies/summary_policy'
 require_relative 'api_query_builders/single_query_param_builder'
 require_relative 'api_query_builders/multi_query_param_builder'
 require_relative 'url_builders/url_builder'
@@ -42,14 +44,12 @@ module Gitlab
         puts Gitlab::Triage::UI.header("Triaging the `#{options.project_id}` project", char: '=')
         puts
 
-        resource_rules.each do |type, resource|
-          puts Gitlab::Triage::UI.header("Processing rules for #{type}", char: '-')
+        resource_rules.each do |resource_type, resource|
+          puts Gitlab::Triage::UI.header("Processing rules for #{resource_type}", char: '-')
           puts
-          resource[:rules].each do |rule|
-            puts Gitlab::Triage::UI.header("Processing rule: **#{rule[:name]}**", char: '-')
-            puts
-            process_rule(type, rule)
-          end
+
+          process_summaries(resource_type, resource[:summaries])
+          process_rules(resource_type, resource[:rules])
         end
       end
 
@@ -94,15 +94,45 @@ module Gitlab
         rule.fetch(:conditions) { {} }
       end
 
-      def rule_actions(rule)
-        rule.fetch(:actions) { {} }
-      end
-
       def rule_limits(rule)
         rule.fetch(:limits) { {} }
       end
 
-      def process_rule(resource_type, rule)
+      def process_summaries(resource_type, summaries)
+        return if summaries.blank?
+
+        summaries.each do |summary|
+          process_summary(resource_type, summary)
+        end
+      end
+
+      def process_rules(resource_type, rules)
+        return if rules.blank?
+
+        rules.each do |rule|
+          process_action(Policies::RulePolicy.new(resource_type, rule, resources_for_rule(resource_type, rule), net))
+        end
+      end
+
+      def process_summary(resource_type, summary)
+        puts Gitlab::Triage::UI.header("Processing summary: **#{summary[:name]}**", char: '~')
+        puts
+
+        resources = resources_for_rules(resource_type, summary[:rules])
+        # { summary_rule => resources }
+        summary_parts = Hash[summary[:rules].zip(resources)]
+
+        process_action(Policies::SummaryPolicy.new(resource_type, summary, summary_parts, net))
+      end
+
+      def resources_for_rules(resource_type, rules)
+        rules.map { |rule| resources_for_rule(resource_type, rule) }
+      end
+
+      def resources_for_rule(resource_type, rule)
+        puts Gitlab::Triage::UI.header("Processing rule: **#{rule[:name]}**", char: '-')
+        resources = []
+
         ExpandCondition.perform(rule_conditions(rule)) do |conditions|
           # retrieving the resources for every rule is inefficient
           # however, previous rules may affect those upcoming
@@ -114,14 +144,18 @@ module Gitlab
           print "* Limiting resources..."
           resources = limit_resources(resources, rule_limits(rule))
           puts "\n* Total after limiting: #{resources.count} resources"
-          Action.process(
-            name: rule[:name],
-            type: resource_type,
-            rules: rule_actions(rule),
-            resources: resources,
-            net: net,
-            dry: options.dry_run)
+          puts
         end
+
+        resources
+      end
+
+      def process_action(policy)
+        Action.process(
+          policy: policy,
+          net: net,
+          dry: options.dry_run)
+        puts
       end
 
       def filter_resources(resources, conditions)

data/lib/gitlab/triage/{action/summarize → entity_builders}/issue_builder.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative '../base'
-require_relative '../../command_builders/text_content_builder'
+require_relative '../command_builders/text_content_builder'
 
 module Gitlab
   module Triage
-    module Action
+    module EntityBuilders
       class IssueBuilder
         attr_reader :title
+        attr_writer :description, :items
 
         def initialize(action, resources, net)
           @title = action[:title]

data/lib/gitlab/triage/policies/base_policy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Triage
+    module Policies
+      BasePolicy = Struct.new(:type, :policy_spec, :resources, :net) do
+        def name
+          @name ||= (policy_spec[:name] || "#{type}-#{object_id}")
+        end
+
+        def actions
+          @actions ||= policy_spec.fetch(:actions) { {} }
+        end
+
+        def summarize?
+          actions.key?(:summarize)
+        end
+
+        def comment?
+          (actions.keys - [:summarize]).any?
+        end
+
+        def build_issue
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/policies/rule_policy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'base_policy'
+require_relative '../entity_builders/issue_builder'
+
+module Gitlab
+  module Triage
+    module Policies
+      class RulePolicy < BasePolicy
+        # Build an issue from a single rule policy
+        def build_issue
+          EntityBuilders::IssueBuilder.new(actions, resources, net)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/policies/summary_policy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base_policy'
+require_relative 'rule_policy'
+require_relative '../entity_builders/issue_builder'
+
+module Gitlab
+  module Triage
+    module Policies
+      class SummaryPolicy < BasePolicy
+        # Build an issue from several rules policies
+        def build_issue
+          EntityBuilders::IssueBuilder.new(actions[:summarize].merge(item: "{{description}}\n\n"), [], net).tap do |issue|
+            issue.items =
+              resources.map do |inner_policy_spec, inner_resources|
+                Policies::RulePolicy.new(type, inner_policy_spec, inner_resources, net).build_issue.description
+              end.join("\n\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/version.rb

@@ -1,5 +1,5 @@
 module Gitlab
   module Triage
-    VERSION = '0.13.0'.freeze
+    VERSION = '0.14.0'.freeze
   end
 end

data/support/.triage-policies.example.yml

@@ -14,6 +14,36 @@ resource_rules:
         actions:
           comment: |
             This issue has been open for one week and is unlabelled
+    summaries:
+      - name: Newest and oldest issues summary
+        actions:
+          summarize:
+            title: "Newest and oldest issues summary"
+            summary: |
+              Please triage the following issues:
+
+              {{items}}
+
+              Please take care of them before the end of #{7.days.from_now.strftime('%Y-%m-%d')}
+
+              /label ~"needs attention"
+        rules:
+          - name: New issues
+            conditions:
+              state: opened
+            limits:
+              most_recent: 2
+            actions:
+              item: "- [ ] [{{title}}]({{web_url}}) {{labels}}"
+              summary: "Please triage the following new issues:\n\n{{items}}"
+          - name: Old issues
+            conditions:
+              state: opened
+            limits:
+              oldest: 2
+            actions:
+              item: "- [ ] [{{title}}]({{web_url}}) {{labels}}"
+              summary: "Please triage the following old issues:\n\n{{items}}"
   merge_requests:
     rules:
       []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-triage
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-12 00:00:00.000000000 Z
+date: 2018-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -135,7 +135,6 @@ files:
 - lib/gitlab/triage/action/base.rb
 - lib/gitlab/triage/action/comment.rb
 - lib/gitlab/triage/action/summarize.rb
-- lib/gitlab/triage/action/summarize/issue_builder.rb
 - lib/gitlab/triage/api_query_builders/base_query_param_builder.rb
 - lib/gitlab/triage/api_query_builders/multi_query_param_builder.rb
 - lib/gitlab/triage/api_query_builders/single_query_param_builder.rb
@@ -147,6 +146,7 @@ files:
 - lib/gitlab/triage/command_builders/status_command_builder.rb
 - lib/gitlab/triage/command_builders/text_content_builder.rb
 - lib/gitlab/triage/engine.rb
+- lib/gitlab/triage/entity_builders/issue_builder.rb
 - lib/gitlab/triage/expand_condition.rb
 - lib/gitlab/triage/expand_condition/expansion.rb
 - lib/gitlab/triage/expand_condition/list.rb
@@ -167,6 +167,9 @@ files:
 - lib/gitlab/triage/network_adapters/base_adapter.rb
 - lib/gitlab/triage/network_adapters/httparty_adapter.rb
 - lib/gitlab/triage/network_adapters/test_adapter.rb
+- lib/gitlab/triage/policies/base_policy.rb
+- lib/gitlab/triage/policies/rule_policy.rb
+- lib/gitlab/triage/policies/summary_policy.rb
 - lib/gitlab/triage/resource/base.rb
 - lib/gitlab/triage/resource/context.rb
 - lib/gitlab/triage/resource/instance_version.rb