Merge branch 'api-priority-labels' into 'master'

Exposes the label priority to the API. Furthermore, it allows the user to modify the priority via the API.

Closes #21269

See merge request !7286

changelogs/unreleased/api-label-priorities.yml

+---
+title: API: Ability to retrieve version information
+merge_request: 7286
+author: Robert Schilling

doc/api/labels.md

@@ -26,7 +26,9 @@ Example response:
       "description": "Bug reported by user",
       "open_issues_count": 1,
       "closed_issues_count": 0,
-      "open_merge_requests_count": 1
+      "open_merge_requests_count": 1,
+      "subscribed": false,
+      "priority": 10
    },
    {
       "color" : "#d9534f",
@@ -34,7 +36,9 @@ Example response:
       "description": "Confirmed issue",
       "open_issues_count": 2,
       "closed_issues_count": 5,
-      "open_merge_requests_count": 0
+      "open_merge_requests_count": 0,
+      "subscribed": false,
+      "priority": null
    },
    {
       "name" : "critical",
@@ -42,7 +46,9 @@ Example response:
       "description": "Critical issue. Need fix ASAP",
       "open_issues_count": 1,
       "closed_issues_count": 3,
-      "open_merge_requests_count": 1
+      "open_merge_requests_count": 1,
+      "subscribed": false,
+      "priority": null
    },
    {
       "name" : "documentation",
@@ -50,7 +56,9 @@ Example response:
       "description": "Issue about documentation",
       "open_issues_count": 1,
       "closed_issues_count": 0,
-      "open_merge_requests_count": 2
+      "open_merge_requests_count": 2,
+      "subscribed": false,
+      "priority": null
    },
    {
       "color" : "#5cb85c",
@@ -58,7 +66,9 @@ Example response:
       "description": "Enhancement proposal",
       "open_issues_count": 1,
       "closed_issues_count": 0,
-      "open_merge_requests_count": 1
+      "open_merge_requests_count": 1,
+      "subscribed": false,
+      "priority": null
    }
 ]
 ```
@@ -80,6 +90,7 @@ POST /projects/:id/labels
 | `name`        | string  | yes      | The name of the label        |
 | `color`       | string  | yes      | The color of the label in 6-digit hex notation with leading `#` sign |
 | `description` | string  | no       | The description of the label |
+| `priority`    | integer | no       | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
 
 ```bash
 curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
@@ -91,7 +102,11 @@ Example response:
 {
    "name" : "feature",
    "color" : "#5843AD",
-   "description":null
+   "open_issues_count": 1,
+   "closed_issues_count": 0,
+   "open_merge_requests_count": 1,
+   "description": null,
+   "priority": null
 }
 ```
 
@@ -127,7 +142,8 @@ Example response:
    "template" : false,
    "project_id" : 1,
    "created_at" : "2015-11-03T21:22:30.737Z",
-   "id" : 9
+   "id" : 9,
+   "priority": null
 }
 ```
 
@@ -151,6 +167,8 @@ PUT /projects/:id/labels
 | `new_name`      | string  | yes if `color` is not provided    | The new name of the label        |
 | `color`         | string  | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign |
 | `description`   | string  | no                                | The new description of the label |
+| `priority`    | integer | no       | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. |
+
 
 ```bash
 curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels"
@@ -162,7 +180,11 @@ Example response:
 {
    "color" : "#8E44AD",
    "name" : "docs",
-   "description": "Documentation"
+   "description": "Documentation",
+   "open_issues_count": 1,
+   "closed_issues_count": 0,
+   "open_merge_requests_count": 1,
+   "priority": null
 }
 ```
 
@@ -197,7 +219,8 @@ Example response:
     "open_issues_count": 0,
     "closed_issues_count": 0,
     "open_merge_requests_count": 0,
-    "subscribed": true
+    "subscribed": true,
+    "priority": null
 }
 ```
 
@@ -232,6 +255,7 @@ Example response:
     "open_issues_count": 0,
     "closed_issues_count": 0,
     "open_merge_requests_count": 0,
-    "subscribed": false
+    "subscribed": false,
+    "priority": null
 }
 ```

lib/api/entities.rb

@@ -438,6 +438,9 @@ module API
 
     class Label < LabelBasic
       expose :open_issues_count, :closed_issues_count, :open_merge_requests_count
+      expose :priority do |label, options|
+        label.priority(options[:project])
+      end
 
       expose :subscribed do |label, options|
         label.subscribed?(options[:current_user])

lib/api/labels.rb

@@ -11,7 +11,7 @@ module API
         success Entities::Label
       end
       get ':id/labels' do
-        present available_labels, with: Entities::Label, current_user: current_user
+        present available_labels, with: Entities::Label, current_user: current_user, project: user_project
       end
 
       desc 'Create a new label' do
@@ -21,6 +21,7 @@ module API
         requires :name, type: String, desc: 'The name of the label to be created'
         requires :color, type: String, desc: "The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)"
         optional :description, type: String, desc: 'The description of label to be created'
+        optional :priority, type: Integer, desc: 'The priority of the label', allow_blank: true
       end
       post ':id/labels' do
         authorize! :admin_label, user_project
@@ -28,10 +29,15 @@ module API
         label = available_labels.find_by(title: params[:name])
         conflict!('Label already exists') if label
 
-        label = user_project.labels.create(declared(params, include_parent_namespaces: false).to_h)
+        priority = params.delete(:priority)
+        label_params = declared(params,
+                                include_parent_namespaces: false,
+                                include_missing: false).to_h
+        label = user_project.labels.create(label_params)
 
         if label.valid?
-          present label, with: Entities::Label, current_user: current_user
+          label.prioritize!(user_project, priority) if priority
+          present label, with: Entities::Label, current_user: current_user, project: user_project
         else
           render_validation_error!(label)
         end
@@ -49,7 +55,7 @@ module API
         label = user_project.labels.find_by(title: params[:name])
         not_found!('Label') unless label
 
-        present label.destroy, with: Entities::Label, current_user: current_user
+        present label.destroy, with: Entities::Label, current_user: current_user, project: user_project
       end
 
       desc 'Update an existing label. At least one optional parameter is required.' do
@@ -60,7 +66,8 @@ module API
         optional :new_name, type: String, desc: 'The new name of the label'
         optional :color, type: String, desc: "The new color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB)"
         optional :description, type: String, desc: 'The new description of label'
-        at_least_one_of :new_name, :color, :description
+        optional :priority, type: Integer, desc: 'The priority of the label', allow_blank: true
+        at_least_one_of :new_name, :color, :description, :priority
       end
       put ':id/labels' do
         authorize! :admin_label, user_project
@@ -68,17 +75,25 @@ module API
         label = user_project.labels.find_by(title: params[:name])
         not_found!('Label not found') unless label
 
-        update_params = declared(params,
-                                 include_parent_namespaces: false,
-                                 include_missing: false).to_h
+        update_priority = params.key?(:priority)
+        priority = params.delete(:priority)
+        label_params = declared(params,
+                                include_parent_namespaces: false,
+                                include_missing: false).to_h
         # Rename new name to the actual label attribute name
-        update_params['name'] = update_params.delete('new_name') if update_params.key?('new_name')
+        label_params[:name] = label_params.delete('new_name') if label_params.key?('new_name')
 
-        if label.update(update_params)
-          present label, with: Entities::Label, current_user: current_user
-        else
-          render_validation_error!(label)
+        render_validation_error!(label) unless label.update(label_params)
+
+        if update_priority
+          if priority.nil?
+            label.unprioritize!(user_project)
+          else
+            label.prioritize!(user_project, priority)
+          end
         end
+
+        present label, with: Entities::Label, current_user: current_user, project: user_project
       end
     end
   end

spec/requests/api/labels_spec.rb

@@ -6,6 +6,7 @@ describe API::API, api: true  do
   let(:user) { create(:user) }
   let(:project) { create(:project, creator_id: user.id, namespace: user.namespace) }
   let!(:label1) { create(:label, title: 'label1', project: project) }
+  let!(:priority_label) { create(:label, title: 'bug', project: project, priority: 3) }
 
   before do
     project.team << [user, :master]
@@ -21,8 +22,16 @@ describe API::API, api: true  do
 
       expect(response).to have_http_status(200)
       expect(json_response).to be_an Array
-      expect(json_response.size).to eq(2)
-      expect(json_response.map { |l| l['name'] }).to match_array([group_label.name, label1.name])
+      expect(json_response.size).to eq(3)
+      expect(json_response.map { |l| l['name'] }).to match_array([group_label.name, priority_label.name, label1.name])
+      expect(json_response.last['name']).to eq(label1.name)
+      expect(json_response.last['color']).to be_present
+      expect(json_response.last['description']).to be_nil
+      expect(json_response.last['open_issues_count']).to eq(0)
+      expect(json_response.last['closed_issues_count']).to eq(0)
+      expect(json_response.last['open_merge_requests_count']).to eq(0)
+      expect(json_response.last['priority']).to be_nil
+      expect(json_response.last['subscribed']).to be_falsey
     end
   end
 
@@ -31,21 +40,39 @@ describe API::API, api: true  do
       post api("/projects/#{project.id}/labels", user),
            name: 'Foo',
            color: '#FFAABB',
-           description: 'test'
+           description: 'test',
+           priority: 2
+
       expect(response).to have_http_status(201)
       expect(json_response['name']).to eq('Foo')
       expect(json_response['color']).to eq('#FFAABB')
       expect(json_response['description']).to eq('test')
+      expect(json_response['priority']).to eq(2)
     end
 
     it 'returns created label when only required params' do
       post api("/projects/#{project.id}/labels", user),
            name: 'Foo & Bar',
            color: '#FFAABB'
+
       expect(response.status).to eq(201)
       expect(json_response['name']).to eq('Foo & Bar')
       expect(json_response['color']).to eq('#FFAABB')
       expect(json_response['description']).to be_nil
+      expect(json_response['priority']).to be_nil
+    end
+
+    it 'creates a prioritized label' do
+      post api("/projects/#{project.id}/labels", user),
+           name: 'Foo & Bar',
+           color: '#FFAABB',
+           priority: 3
+
+      expect(response.status).to eq(201)
+      expect(json_response['name']).to eq('Foo & Bar')
+      expect(json_response['color']).to eq('#FFAABB')
+      expect(json_response['description']).to be_nil
+      expect(json_response['priority']).to eq(3)
     end
 
     it 'returns a 400 bad request if name not given' do
@@ -95,6 +122,15 @@ describe API::API, api: true  do
       expect(json_response['message']).to eq('Label already exists')
     end
 
+    it 'returns 400 for invalid priority' do
+      post api("/projects/#{project.id}/labels", user),
+           name: 'Foo',
+           color: '#FFAAFFFF',
+           priority: 'foo'
+
+      expect(response).to have_http_status(400)
+    end
+
     it 'returns 409 if label already exists in project' do
       post api("/projects/#{project.id}/labels", user),
            name: 'label1',
@@ -155,11 +191,43 @@ describe API::API, api: true  do
 
     it 'returns 200 if description is changed' do
       put api("/projects/#{project.id}/labels", user),
-          name: 'label1',
+          name: 'bug',
           description: 'test'
+
       expect(response).to have_http_status(200)
-      expect(json_response['name']).to eq(label1.name)
+      expect(json_response['name']).to eq(priority_label.name)
       expect(json_response['description']).to eq('test')
+      expect(json_response['priority']).to eq(3)
+    end
+
+    it 'returns 200 if priority is changed' do
+      put api("/projects/#{project.id}/labels", user),
+           name: 'bug',
+           priority: 10
+
+      expect(response.status).to eq(200)
+      expect(json_response['name']).to eq(priority_label.name)
+      expect(json_response['priority']).to eq(10)
+    end
+
+    it 'returns 200 if a priority is added' do
+      put api("/projects/#{project.id}/labels", user),
+           name: 'label1',
+           priority: 3
+
+      expect(response.status).to eq(200)
+      expect(json_response['name']).to eq(label1.name)
+      expect(json_response['priority']).to eq(3)
+    end
+
+    it 'returns 200 if the priority is removed' do
+      put api("/projects/#{project.id}/labels", user),
+          name: priority_label.name,
+          priority: nil
+
+      expect(response.status).to eq(200)
+      expect(json_response['name']).to eq(priority_label.name)
+      expect(json_response['priority']).to be_nil
     end
 
     it 'returns 404 if label does not exist' do
@@ -178,7 +246,7 @@ describe API::API, api: true  do
     it 'returns 400 if no new parameters given' do
       put api("/projects/#{project.id}/labels", user), name: 'label1'
       expect(response).to have_http_status(400)
-      expect(json_response['error']).to eq('new_name, color, description are missing, '\
+      expect(json_response['error']).to eq('new_name, color, description, priority are missing, '\
                                            'at least one parameter must be provided')
     end
 
@@ -206,6 +274,14 @@ describe API::API, api: true  do
       expect(response).to have_http_status(400)
       expect(json_response['message']['color']).to eq(['must be a valid color code'])
     end
+
+    it 'returns 400 for invalid priority' do
+      post api("/projects/#{project.id}/labels", user),
+           name: 'Foo',
+           priority: 'foo'
+
+      expect(response).to have_http_status(400)
+    end
   end
 
   describe "POST /projects/:id/labels/:label_id/subscription" do