gitlab-triage 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07c73a42510a969fbfbd9d37b8c0cf3aa5b7194f411845ffa85df71bdd17e014
-  data.tar.gz: 92c16e24e3b60a68cbda012ca44cbef9e20e3d8143425ef6506db0817ee2e80d
+  metadata.gz: 0b9611f0a3f4f58779cf16cfa76d2dc93889646dc7566b8dc75116838f362940
+  data.tar.gz: 6d8c4675ead2c209ab18df6f8bb6068cf9c2a80f262d7d6759921f90679f1e47
 SHA512:
-  metadata.gz: e078932be7f117f6f6c4ad1bed68b8fb217dec19ffb60d0010507f009cdaeb1c21e718d729795317eaae4c91c30ddaed6acf16c0f75c03859516e23893af7d6f
-  data.tar.gz: c228d7ae359adcc1b4d1f8b9e058242a28f8c7c7f9500e7670c1ee9808d6098e7424c266188d3ebb0c9bd7c4bbe7354ff9dd1feac8a31167d54a28b14014106e
+  metadata.gz: 521a204ed0b650f6f31d8cb78583525ea58f2fb9378db976bf1a1e42af3a58b475480c8128cc59f43fdf065214e23557356502c4ee2340d444806fe56a3cfe33
+  data.tar.gz: a9d972bdd97dc71c4759849ec6b17a6a0f1f0bfc634c3aaf9c895b1f5e7e53a119642ebad19b39ffb156a583efaf06c0ce6a5b5cfb6f27cb384fc963252e215b

data/.gitlab-ci.yml

@@ -54,15 +54,6 @@ specs:
   script:
     - bundle exec rake spec
 
-build:
-  <<: *pull-cache
-  stage: test
-  script:
-    - bundle exec rake build
-    - bundle exec rake clobber
-  except:
-    - schedules
-
 codequality:
   <<: *pull-cache
   image: docker:latest
@@ -94,7 +85,9 @@ dry-run:bin:gitlab-org/triage:
   <<: *pull-cache
   stage: triage
   script:
-    - bundle exec bin/gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/triage
+    - bundle exec rake install:local
+    - gitlab-triage --help
+    - gitlab-triage --dry-run --token $API_TOKEN --project-id $CI_PROJECT_PATH
   except:
     - schedules
 
@@ -102,7 +95,9 @@ dry-run:bin:gitlab-org/gitlab-ce:
   <<: *pull-cache
   stage: triage
   script:
-    - bundle exec bin/gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/gitlab-ce
+    - bundle exec rake install:local
+    - gitlab-triage --help
+    - gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/gitlab-ce
   when: manual
   except:
     - schedules
@@ -113,7 +108,7 @@ dry-run:gem:gitlab-org/triage:
   script:
     - gem install gitlab-triage
     - gitlab-triage --help
-    - gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/triage
+    - gitlab-triage --dry-run --token $API_TOKEN --project-id $CI_PROJECT_PATH
   when: manual
   except:
     - schedules
@@ -133,6 +128,6 @@ run:triage:triage:
   stage: triage
   script:
     - gem install gitlab-triage
-    - gitlab-triage --token $API_TOKEN --project-id gitlab-org/triage
+    - gitlab-triage --token $API_TOKEN --project-id $CI_PROJECT_PATH
   only:
     - schedules

data/README.md

@@ -1,13 +1,285 @@
 [![pipeline status](https://gitlab.com/gitlab-org/triage/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/triage/commits/master)
 
-## GitLab Triage Project
+# GitLab Triage Project
 
-This project contains scripts used for triaging Issues and Merge Requests in  [GitLab-CE Project](https://gitlab.com/gitlab-org/gitlab-ce) projects and enforcing our Issue Triage policies as well of generating data related to triaging issues more effectively.
-The scripts found here may be useful for triaging issues in other projects too.
+This project contains the library and pipeline definition to enable automated triaging of issues in the [GitLab-CE Project](https://gitlab.com/gitlab-org/gitlab-ce).
 
-- We define the policies in code in a public project where those interested can raise issues surrounding our policies.
-- We use scheduled pipelines to run the scripts to enforce our policies on a daily basis.
+## gitlab-triage gem
 
-## Suggesting new policies or suggesting changes to policies
+### Summary
 
-Please feel free to [open an issue](https://gitlab.com/gitlab-org/triage/issues/new) about creating, editing or deleting a policy. Please select the policy issue template when creating an issue.
+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?
+
+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.
+
+### Defining a policy
+
+Policies are defined in a policy file (by default [.triage-policies.yml](.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
+
+Select which resource to add the policy to:
+- `issues`
+- `merge_requests`
+
+And create an array of `rules` to define your policies:
+
+For example:
+
+```yml
+resource_rules:
+  issues:
+    rules:
+      - name: My policy
+        conditions:
+          date:
+            attribute: updated_at
+            condition: older_than
+            interval_type: days
+            interval: 5
+          state: opened
+          label:
+            - No label
+        actions:
+          labels:
+            - needs attention
+          mention:
+            - markglenfletcher
+          comment: |
+            This issue is unlabelled after 5 days. It needs attention.
+  merge_requests:
+    rules:
+      []
+```
+
+### Fields
+
+A policy consists of the following fields:
+- [Name field](#name-field)
+- [Conditions field](#conditions-field)
+- [Actions field](#actions-field)
+
+#### Name field
+
+The name field is used to describe the purpose of the individual policy.
+
+Example:
+
+```yml
+name: Policy name
+```
+
+#### Conditions field
+
+Used to declare a condition that must be satisfied by a resource before actions will be taken.
+
+Available condition types:
+- [`date` condition](#date-condition)
+- [`milestone` condition](#milestone-condition)
+- [`state` condition](#state-condition)
+- [`upvotes` condition](#upvotes-condition)
+- [`labels` condition](#labels-condition)
+
+##### Date condition
+
+Accepts a hash of fields.
+
+| Field           | Type    | Values                              | Required  |
+| ---------       | ----    | ----                                | --------  |
+| `attribute`     | string  | `created_at`, `updated_at`          | yes       |
+| `condition`     | string  | `older_than`, `newer_than`          | yes       |
+| `interval_type` | string  | `days`, `weeks`, `months`, `years`  | yes       |
+| `interval`      | integer | integer                             | yes       |
+
+Example:
+
+```yml
+conditions:
+  date:
+    attribute: updated_at
+    condition: older_than
+    interval_type: months
+    interval: 12
+```
+
+##### Milestone condition
+
+Accepts an array of strings. Each element is the name of a milestone to filter upon.
+
+> Note: **All** specified milestones must be present on the resource for the condition to be satisfied
+
+Example:
+
+```yml
+conditions:
+  milestone:
+    - v1
+    - v2
+```
+
+##### State condition
+
+Accepts a string.
+
+| State           | Type    | Value     |
+| ---------       | ----    | ------    |
+| Closed issues   | string  | `closed`  |
+| Open issues     | string  | `opened`  |
+
+Example:
+
+```yml
+conditions:
+  state: opened
+```
+
+##### Upvotes condition
+
+Accepts a hash of fields.
+
+| Field           | Type    | Values                              | Required  |
+| ---------       | ----    | ----                                | --------  |
+| `attribute`     | string  | `upvotes`, `downvotes`              | yes       |
+| `condition`     | string  | `less_than`, `greater_than`         | yes       |
+| `threshold`     | integer | integer                             | yes       |
+
+Example:
+
+```yml
+conditions:
+  upvotes:
+    attribute: upvotes
+    condition: less_than
+    threshold: 10
+```
+
+##### Labels condition
+
+Accepts an array of strings. Each element in the array represents the name of a label to filter on.
+
+> Note: **All** specified labels must be present on the resource for the condition to be satisfied
+
+Example:
+
+```yml
+conditions:
+  labels:
+    - feature proposal
+```
+
+#### Actions field
+
+Used to declare an action to be carried out on a resource if **all** conditions are satisfied.
+
+Available action types:
+- [`label` action](#label-action)
+- [`status` action](#status-action)
+- [`mention` action](#mention-action)
+- [`comment` action](#comment-action)
+
+##### Label action
+
+Adds a number of labels to the resource.
+
+Accepts an array of strings. Each element is the name of a label to add.
+
+Example:
+
+```yml
+actions:
+  label:
+    - feature proposal
+    - awaiting feedback
+```
+
+##### Status action
+
+Changes the status of the resource.
+
+Accepts a string.
+
+| State transition    | Type    | Value     |
+| ---------           | ----    | ------    |
+| Close the resource  | string  | `close`   |
+| Reopen the resource | string  | `reopen`  |
+
+Example:
+
+```yml
+actions:
+  status: close
+```
+
+##### Mention action
+
+Mentions a number of users.
+
+Accepts an array of strings. Each element is the username of a user to mention.
+
+Example:
+
+```yml
+actions:
+  mention:
+    - rymai
+    - markglenfletcher
+```
+
+##### Comment action
+
+Adds a comment to the resource.
+
+Accepts a string.
+
+Example:
+
+```yml
+actions:
+  comment: |
+    Closing this issue automatically
+```
+
+### Usage
+
+```
+Usage: gitlab-triage [options]
+
+    -n, --dry-run                    Don't actually update anything, just print
+    -f, --policies-file [string]     A valid policies YML file
+    -p, --project-id [string]        A project ID or path
+    -t, --token [string]             A valid API token
+    -d, --debug                      Print debug information
+    -h, --help                       Print help message
+        --init                       Initialize the project with a policy file
+        --init-ci                    Initialize the project with a .gitlab-ci.yml file
+```
+
+#### Local
+
+```
+gem install gitlab-triage
+gitlab-triage --help
+gitlab-triage --dry-run --token $API_TOKEN --project-id gitlab-org/triage
+```
+
+#### GitLab CI pipeline
+
+You can enforce policies using a scheduled pipeline:
+
+```yml
+run:triage:triage:
+  stage: triage
+  script:
+    - gem install gitlab-triage
+    - gitlab-triage --token $API_TOKEN --project-id $CI_PROJECT_PATH
+  only:
+    - schedules
+```
+
+> Note: You can use the [`--init-ci`](#usage) option to add an example [`.gitlab-ci.yml` file](support/.gitlab-ci.example.yml) to your project

data/bin/gitlab-triage

@@ -44,6 +44,16 @@ class TriageOptionParser
           $stdout.puts opts
           exit
         end
+
+        opts.on('--init', 'Initialize the project with a policy file') do
+          FileUtils.cp('./support/.triage-policies.example.yml', './.triage-policies.yml')
+          exit
+        end
+
+        opts.on('--init-ci', 'Initialize the project with a .gitlab-ci.yml file') do
+          FileUtils.cp('./support/.gitlab-ci.example.yml', './.gitlab-ci.yml')
+          exit
+        end
       end
 
       parser.parse!(argv)

data/lib/gitlab/triage/network.rb

@@ -30,7 +30,12 @@ module Gitlab
       end
 
       def post_api(token, url, body)
-        @adapter.post(token, url, body)
+        execute_with_retry(Net::ReadTimeout) do
+          @adapter.post(token, url, body)
+        end
+
+      rescue Net::ReadTimeout
+        false
       end
     end
   end

data/lib/gitlab/triage/version.rb

@@ -1,5 +1,5 @@
 module Gitlab
   module Triage
-    VERSION = '0.0.3'.freeze
+    VERSION = '0.1.0'.freeze
   end
 end

data/support/.gitlab-ci.example.yml

@@ -0,0 +1,22 @@
+image: ruby:2.4
+
+stages:
+  - triage
+
+dry-run:triage:
+  stage: triage
+  script:
+    - gem install gitlab-triage
+    - gitlab-triage --help
+    - gitlab-triage --dry-run --token $API_TOKEN --project-id $CI_PROJECT_PATH
+  when: manual
+  except:
+    - schedules
+
+run:triage:
+  stage: triage
+  script:
+    - gem install gitlab-triage
+    - gitlab-triage --token $API_TOKEN --project-id $CI_PROJECT_PATH
+  only:
+    - schedules

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

@@ -0,0 +1,19 @@
+resource_rules:
+  issues:
+    rules:
+      - name: Comment 1 week old, unlabelled issues
+        conditions:
+          date:
+            attribute: created_at
+            condition: older_than
+            interval_type: week
+            interval: 1
+          labels:
+            - No label
+          state: opened
+        actions:
+          comment: |
+            This issue has been open for one week and is unlabelled
+  merge_requests:
+    rules:
+      []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-triage
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - GitLab
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-10 00:00:00.000000000 Z
+date: 2017-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -135,6 +135,8 @@ files:
 - lib/gitlab/triage/ui.rb
 - lib/gitlab/triage/url_builders/url_builder.rb
 - lib/gitlab/triage/version.rb
+- support/.gitlab-ci.example.yml
+- support/.triage-policies.example.yml
 homepage: https://gitlab.com/gitlab-org/triage
 licenses:
 - MIT