Add some API endpoints for time tracking.

New endpoints are:

POST :project_id/(issues|merge_requests)/(:issue_id|:merge_request_id)/time_estimate"

POST :project_id/(issues|merge_requests)/(:issue_id|:merge_request_id)/reset_time_estimate"

POST :project_id/(issues|merge_requests)/(:issue_id|:merge_request_id)/add_spent_time"

POST :project_id/(issues|merge_requests)/(:issue_id|:merge_request_id)/reset_spent_time"

GET  :project_id/(issues|merge_requests)/(:issue_id|:merge_request_id)/time_stats"

Author: rudasa

app/models/concerns/time_trackable.rb

@@ -9,27 +9,32 @@ module TimeTrackable
   extend ActiveSupport::Concern
 
   included do
-    attr_reader :time_spent
+    attr_reader :time_spent, :time_spent_user
 
     alias_method :time_spent?, :time_spent
 
     default_value_for :time_estimate, value: 0, allows_nil: false
 
+    validates :time_estimate, numericality: { message: 'has an invalid format' }, allow_nil: false
+    validate  :check_negative_time_spent
+
     has_many :timelogs, as: :trackable, dependent: :destroy
   end
 
-  def spend_time(seconds, user)
-    return if seconds == 0
+  def spend_time(options)
+    @time_spent = options[:duration]
+    @time_spent_user = options[:user]
+    @original_total_time_spent = nil
 
-    @time_spent = seconds
-    @time_spent_user = user
+    return if @time_spent == 0
 
-    if seconds == :reset
+    if @time_spent == :reset
       reset_spent_time
     else
       add_or_subtract_spent_time
     end
   end
+  alias_method :spend_time=, :spend_time
 
   def total_time_spent
     timelogs.sum(:time_spent)
@@ -50,9 +55,18 @@ def reset_spent_time
   end
 
   def add_or_subtract_spent_time
-    # Exit if time to subtract exceeds the total time spent.
-    return if time_spent < 0 && (time_spent.abs > total_time_spent)
-
     timelogs.new(time_spent: time_spent, user: @time_spent_user)
   end
+
+  def check_negative_time_spent
+    return if time_spent.nil? || time_spent == :reset
+
+    # we need to cache the total time spent so multiple calls to #valid?
+    # doesn't give a false error
+    @original_total_time_spent ||= total_time_spent
+
+    if time_spent < 0 && (time_spent.abs > @original_total_time_spent)
+      errors.add(:time_spent, 'Time to subtract exceeds the total time spent')
+    end
+  end
 end

app/services/issuable_base_service.rb

@@ -164,7 +164,6 @@ def create_issuable(issuable, attributes, label_ids:)
   def create(issuable)
     merge_slash_commands_into_params!(issuable)
     filter_params(issuable)
-    change_time_spent(issuable)
 
     params.delete(:state_event)
     params[:author] ||= current_user
@@ -207,14 +206,13 @@ def update(issuable)
     change_subscription(issuable)
     change_todo(issuable)
     filter_params(issuable)
-    time_spent = change_time_spent(issuable)
     old_labels = issuable.labels.to_a
     old_mentioned_users = issuable.mentioned_users.to_a
 
     label_ids = process_label_ids(params, existing_label_ids: issuable.label_ids)
     params[:label_ids] = label_ids if labels_changing?(issuable.label_ids, label_ids)
 
-    if (params.present? || time_spent) && update_issuable(issuable, params)
+    if params.present? && update_issuable(issuable, params)
       # We do not touch as it will affect a update on updated_at field
       ActiveRecord::Base.no_touching do
         handle_common_system_notes(issuable, old_labels: old_labels)
@@ -261,12 +259,6 @@ def change_todo(issuable)
     end
   end
 
-  def change_time_spent(issuable)
-    time_spent = params.delete(:spend_time)
-
-    issuable.spend_time(time_spent, current_user) if time_spent
-  end
-
   def has_changes?(issuable, old_labels: [])
     valid_attrs = [:title, :description, :assignee_id, :milestone_id, :target_branch]
 

app/services/slash_commands/interpret_service.rb

@@ -262,13 +262,10 @@ def extractor
       current_user.can?(:"admin_#{issuable.to_ability_name}", issuable)
     end
     command :spend do |raw_duration|
-      reduce_time = raw_duration.sub!(/\A-/, '')
       time_spent = Gitlab::TimeTrackingFormatter.parse(raw_duration)
 
       if time_spent
-        time_spent *= -1 if reduce_time
-
-        @updates[:spend_time] = time_spent
+        @updates[:spend_time] = { duration: time_spent, user: current_user }
       end
     end
 
@@ -287,7 +284,7 @@ def extractor
         current_user.can?(:"admin_#{issuable.to_ability_name}", project)
     end
     command :remove_time_spent do
-      @updates[:spend_time] = :reset
+      @updates[:spend_time] = { duration: :reset, user: current_user }
     end
 
     # This is a dummy command, so that it appears in the autocomplete commands

changelogs/unreleased/time-tracking-api.yml

@@ -0,0 +1,4 @@
+---
+title: Add new endpoints for Time Tracking.
+merge_request: 8483
+author:

doc/api/issues.md

@@ -712,6 +712,146 @@ Example response:
 }
 ```
 
+## Set a time estimate for an issue
+
+Sets an estimated time of work for this issue.
+
+```
+POST /projects/:id/issues/:issue_id/time_estimate
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/time_estimate?duration=3h30m
+```
+
+Example response:
+
+```json
+{
+  "human_time_estimate": "3h 30m",
+  "human_total_time_spent": null,
+  "time_estimate": 12600,
+  "total_time_spent": 0
+}
+```
+
+## Reset the time estimate for an issue
+
+Resets the estimated time for this issue to 0 seconds.
+
+```
+POST /projects/:id/issues/:issue_id/reset_time_estimate
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/reset_time_estimate
+```
+
+Example response:
+
+```json
+{
+  "human_time_estimate": null,
+  "human_total_time_spent": null,
+  "time_estimate": 0,
+  "total_time_spent": 0
+}
+```
+
+## Add spent time for an issue
+
+Adds spent time for this issue
+
+```
+POST /projects/:id/issues/:issue_id/add_spent_time
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+| `duration` | string | yes | The duration in human format. e.g: 3h30m |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/add_spent_time?duration=1h
+```
+
+Example response:
+
+```json
+{
+  "human_time_estimate": null,
+  "human_total_time_spent": "1h",
+  "time_estimate": 0,
+  "total_time_spent": 3600
+}
+```
+
+## Reset spent time for an issue
+
+Resets the total spent time for this issue to 0 seconds.
+
+```
+POST /projects/:id/issues/:issue_id/reset_spent_time
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/reset_spent_time
+```
+
+Example response:
+
+```json
+{
+  "human_time_estimate": null,
+  "human_total_time_spent": null,
+  "time_estimate": 0,
+  "total_time_spent": 0
+}
+```
+
+## Get time tracking stats
+
+```
+GET /projects/:id/issues/:issue_id/time_stats
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes   | The ID of a project |
+| `issue_id` | integer | yes | The ID of a project's issue |
+
+```bash
+curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/time_stats
+```
+
+Example response:
+
+```json
+{
+  "human_time_estimate": "2h",
+  "human_total_time_spent": "1h",
+  "time_estimate": 7200,
+  "total_time_spent": 3600
+}
+```
+
 ## Comments on issues
 
 Comments are done via the [notes](notes.md) resource.