Issue time estimate, meaningful time tracking

models/issues/comment.go

@@ -114,6 +114,8 @@ const (
 
 	CommentTypePin   // 36 pin Issue
 	CommentTypeUnpin // 37 unpin Issue
+
+	CommentTypeChangeTimeEstimate // 38 Change time estimate
 )
 
 var commentStrings = []string{
@@ -153,6 +155,7 @@ var commentStrings = []string{
 	"change_issue_ref",
 	"pull_scheduled_merge",
 	"pull_cancel_scheduled_merge",
+	"change_time_estimate",
 	"pin",
 	"unpin",
 }

models/issues/issue.go

@@ -147,6 +147,9 @@ type Issue struct {
 
 	// For view issue page.
 	ShowRole RoleDescriptor `xorm:"-"`
+
+	// Time estimate
+	TimeEstimate int64 `xorm:"NOT NULL DEFAULT 0"`
 }
 
 var (
@@ -934,3 +937,33 @@ func insertIssue(ctx context.Context, issue *Issue) error {
 
 	return nil
 }
+
+// ChangeIssueTimeEstimate changes the plan time of this issue, as the given user.
+func ChangeIssueTimeEstimate(issue *Issue, doer *user_model.User, timeEstimate int64) (err error) {
+	ctx, committer, err := db.TxContext(db.DefaultContext)
+	if err != nil {
+		return err
+	}
+	defer committer.Close()
+
+	if err = UpdateIssueCols(ctx, &Issue{ID: issue.ID, TimeEstimate: timeEstimate}, "time_estimate"); err != nil {
+		return fmt.Errorf("updateIssueCols: %w", err)
+	}
+
+	if err = issue.LoadRepo(ctx); err != nil {
+		return fmt.Errorf("loadRepo: %w", err)
+	}
+
+	opts := &CreateCommentOptions{
+		Type:    CommentTypeChangeTimeEstimate,
+		Doer:    doer,
+		Repo:    issue.Repo,
+		Issue:   issue,
+		Content: fmt.Sprintf("%d", timeEstimate),
+	}
+	if _, err = CreateComment(ctx, opts); err != nil {
+		return fmt.Errorf("createComment: %w", err)
+	}
+
+	return committer.Commit()
+}

models/migrations/migrations.go

@@ -591,6 +591,8 @@ var migrations = []Migration{
 
 	// v299 -> v300
 	NewMigration("Add content version to issue and comment table", v1_23.AddContentVersionToIssueAndComment),
+	// v300 -> v301
+	NewMigration("Add TimeEstimate to issue table", v1_23.AddTimeEstimateColumnToIssueTable),
 }
 
 // GetCurrentDBVersion returns the current db version

models/migrations/v1_23/v300.go

@@ -0,0 +1,16 @@
+// Copyright 2024 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package v1_23 //nolint
+
+import (
+	"xorm.io/xorm"
+)
+
+func AddTimeEstimateColumnToIssueTable(x *xorm.Engine) error {
+	type Issue struct {
+		TimeEstimate int64 `xorm:"NOT NULL DEFAULT 0"`
+	}
+
+	return x.Sync(new(Issue))
+}

modules/templates/helper.go

@@ -66,12 +66,14 @@ func NewFuncMap() template.FuncMap {
 
 		// -----------------------------------------------------------------
 		// time / number / format
-		"FileSize":      base.FileSize,
-		"CountFmt":      base.FormatNumberSI,
-		"TimeSince":     timeutil.TimeSince,
-		"TimeSinceUnix": timeutil.TimeSinceUnix,
-		"DateTime":      timeutil.DateTime,
-		"Sec2Time":      util.SecToTime,
+		"FileSize":          base.FileSize,
+		"CountFmt":          base.FormatNumberSI,
+		"TimeSince":         timeutil.TimeSince,
+		"TimeSinceUnix":     timeutil.TimeSinceUnix,
+		"DateTime":          timeutil.DateTime,
+		"Sec2Time":          util.SecToTime,
+		"SecToTimeExact":    util.SecToTimeExact,
+		"TimeEstimateToStr": util.TimeEstimateToStr,
 		"LoadTimes": func(startTime time.Time) string {
 			return fmt.Sprint(time.Since(startTime).Nanoseconds()/1e6) + "ms"
 		},

modules/util/sec_to_time.go

@@ -66,6 +66,43 @@ func SecToTime(durationVal any) string {
 	return strings.TrimRight(formattedTime, " ")
 }
 
+func SecToTimeExact(duration int64, withSeconds bool) string {
+	formattedTime := ""
+
+	// The following four variables are calculated by taking
+	// into account the previously calculated variables, this avoids
+	// pitfalls when using remainders. As that could lead to incorrect
+	// results when the calculated number equals the quotient number.
+	remainingDays := duration / (60 * 60 * 24)
+	years := remainingDays / 365
+	remainingDays -= years * 365
+	months := remainingDays * 12 / 365
+	remainingDays -= months * 365 / 12
+	weeks := remainingDays / 7
+	remainingDays -= weeks * 7
+	days := remainingDays
+
+	// The following three variables are calculated without depending
+	// on the previous calculated variables.
+	hours := (duration / 3600) % 24
+	minutes := (duration / 60) % 60
+	seconds := duration % 60
+
+	// Show exact time information
+	formattedTime = formatTime(years, "year", formattedTime)
+	formattedTime = formatTime(months, "month", formattedTime)
+	formattedTime = formatTime(weeks, "week", formattedTime)
+	formattedTime = formatTime(days, "day", formattedTime)
+	formattedTime = formatTime(hours, "hour", formattedTime)
+	formattedTime = formatTime(minutes, "minute", formattedTime)
+	if withSeconds {
+		formattedTime = formatTime(seconds, "second", formattedTime)
+	}
+
+	// The formatTime() function always appends a space at the end. This will be trimmed
+	return strings.TrimRight(formattedTime, " ")
+}
+
 // formatTime appends the given value to the existing forammattedTime. E.g:
 // formattedTime = "1 year"
 // input: value = 3, name = "month"

modules/util/time_str.go

@@ -0,0 +1,99 @@
+// Copyright 2022 Gitea. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package util
+
+import (
+	"fmt"
+	"math"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+var (
+	// Time estimate match regex
+	rTimeEstimateOnlyHours = regexp.MustCompile(`^([\d]+)$`)
+	rTimeEstimateWeeks     = regexp.MustCompile(`([\d]+)w`)
+	rTimeEstimateDays      = regexp.MustCompile(`([\d]+)d`)
+	rTimeEstimateHours     = regexp.MustCompile(`([\d]+)h`)
+	rTimeEstimateMinutes   = regexp.MustCompile(`([\d]+)m`)
+)
+
+// TimeEstimateFromStr returns time estimate in seconds from formatted string
+func TimeEstimateFromStr(timeStr string) int64 {
+	timeTotal := 0
+
+	// If single number entered, assume hours
+	timeStrMatches := rTimeEstimateOnlyHours.FindStringSubmatch(timeStr)
+	if len(timeStrMatches) > 0 {
+		raw, _ := strconv.Atoi(timeStrMatches[1])
+		timeTotal += raw * (60 * 60)
+	} else {
+		// Find time weeks
+		timeStrMatches = rTimeEstimateWeeks.FindStringSubmatch(timeStr)
+		if len(timeStrMatches) > 0 {
+			raw, _ := strconv.Atoi(timeStrMatches[1])
+			timeTotal += raw * (60 * 60 * 24 * 7)
+		}
+
+		// Find time days
+		timeStrMatches = rTimeEstimateDays.FindStringSubmatch(timeStr)
+		if len(timeStrMatches) > 0 {
+			raw, _ := strconv.Atoi(timeStrMatches[1])
+			timeTotal += raw * (60 * 60 * 24)
+		}
+
+		// Find time hours
+		timeStrMatches = rTimeEstimateHours.FindStringSubmatch(timeStr)
+		if len(timeStrMatches) > 0 {
+			raw, _ := strconv.Atoi(timeStrMatches[1])
+			timeTotal += raw * (60 * 60)
+		}
+
+		// Find time minutes
+		timeStrMatches = rTimeEstimateMinutes.FindStringSubmatch(timeStr)
+		if len(timeStrMatches) > 0 {
+			raw, _ := strconv.Atoi(timeStrMatches[1])
+			timeTotal += raw * (60)
+		}
+	}
+
+	return int64(timeTotal)
+}
+
+// TimeEstimateStr returns formatted time estimate string from seconds (e.g. "2w 4d 12h 5m")
+func TimeEstimateToStr(amount int64) string {
+	var timeParts []string
+
+	timeSeconds := float64(amount)
+
+	// Format weeks
+	weeks := math.Floor(timeSeconds / (60 * 60 * 24 * 7))
+	if weeks > 0 {
+		timeParts = append(timeParts, fmt.Sprintf("%dw", int64(weeks)))
+	}
+	timeSeconds -= weeks * (60 * 60 * 24 * 7)
+
+	// Format days
+	days := math.Floor(timeSeconds / (60 * 60 * 24))
+	if days > 0 {
+		timeParts = append(timeParts, fmt.Sprintf("%dd", int64(days)))
+	}
+	timeSeconds -= days * (60 * 60 * 24)
+
+	// Format hours
+	hours := math.Floor(timeSeconds / (60 * 60))
+	if hours > 0 {
+		timeParts = append(timeParts, fmt.Sprintf("%dh", int64(hours)))
+	}
+	timeSeconds -= hours * (60 * 60)
+
+	// Format minutes
+	minutes := math.Floor(timeSeconds / (60))
+	if minutes > 0 {
+		timeParts = append(timeParts, fmt.Sprintf("%dm", int64(minutes)))
+	}
+
+	return strings.Join(timeParts, " ")
+}

options/locale/locale_en-US.ini

@@ -1482,6 +1482,11 @@ issues.add_assignee_at = `was assigned by <b>%s</b> %s`
 issues.remove_assignee_at = `was unassigned by <b>%s</b> %s`
 issues.remove_self_assignment = `removed their assignment %s`
 issues.change_title_at = `changed title from <b><strike>%s</strike></b> to <b>%s</b> %s`
+issues.time_estimate = `Time Estimate`
+issues.add_time_estimate = `3w 4d 12h`
+issues.change_time_estimate_at = `changed time estimate to <b>%s</b> %s`
+issues.remove_time_estimate = `removed time estimate %s`
+issues.time_estimate_invalid = `Time estimate format is invalid`
 issues.change_ref_at = `changed reference from <b><strike>%s</strike></b> to <b>%s</b> %s`
 issues.remove_ref_at = `removed reference <b>%s</b> %s`
 issues.add_ref_at = `added reference <b>%s</b> %s`
@@ -1652,20 +1657,20 @@ issues.start_tracking_history = `started working %s`
 issues.tracker_auto_close = Timer will be stopped automatically when this issue gets closed
 issues.tracking_already_started = `You have already started time tracking on <a href="%s">another issue</a>!`
 issues.stop_tracking = Stop Timer
-issues.stop_tracking_history = `stopped working %s`
+issues.stop_tracking_history = `worked for <b>%s</b> %s`
 issues.cancel_tracking = Discard
 issues.cancel_tracking_history = `canceled time tracking %s`
 issues.add_time = Manually Add Time
 issues.del_time = Delete this time log
 issues.add_time_short = Add Time
 issues.add_time_cancel = Cancel
-issues.add_time_history = `added spent time %s`
-issues.del_time_history= `deleted spent time %s`
+issues.add_time_history = `added spent time <b>%s</b> %s`
+issues.del_time_history= `deleted spent time <b>%s</b> %s`
 issues.add_time_hours = Hours
 issues.add_time_minutes = Minutes
 issues.add_time_sum_to_small = No time was entered.
 issues.time_spent_total = Total Time Spent
-issues.time_spent_from_all_authors = `Total Time Spent: %s`
+issues.time_spent_from_all_authors = `Total Time Spent:`
 issues.due_date = Due Date
 issues.invalid_due_date_format = "Due date format must be 'yyyy-mm-dd'."
 issues.error_modifying_due_date = "Failed to modify the due date."

routers/web/repo/issue.go

@@ -13,6 +13,7 @@ import (
 	"math/big"
 	"net/http"
 	"net/url"
+	"regexp"
 	"slices"
 	"sort"
 	"strconv"
@@ -1774,6 +1775,9 @@ func ViewIssue(ctx *context.Context) {
 					comment.Content = comment.Content[1:]
 				}
 			}
+		} else if comment.Type == issues_model.CommentTypeChangeTimeEstimate {
+			timeSec, _ := util.ToInt64(comment.Content)
+			comment.Content = util.SecToTimeExact(timeSec, timeSec < 60)
 		}
 
 		if comment.Type == issues_model.CommentTypeClose || comment.Type == issues_model.CommentTypeMergePull {
@@ -2215,6 +2219,57 @@ func UpdateIssueTitle(ctx *context.Context) {
 	})
 }
 
+// UpdateIssueTimeEstimate change issue's planned time
+var (
+	rTimeEstimateStr          = regexp.MustCompile(`^([\d]+w)?\s?([\d]+d)?\s?([\d]+h)?\s?([\d]+m)?$`)
+	rTimeEstimateStrHoursOnly = regexp.MustCompile(`^([\d]+)$`)
+)
+
+func UpdateIssueTimeEstimate(ctx *context.Context) {
+	issue := GetActionIssue(ctx)
+	if ctx.Written() {
+		return
+	}
+
+	if !ctx.IsSigned || (!issue.IsPoster(ctx.Doer.ID) && !ctx.Repo.CanWriteIssuesOrPulls(issue.IsPull)) {
+		ctx.Error(http.StatusForbidden)
+		return
+	}
+
+	url := issue.Link()
+
+	timeStr := ctx.FormString("time_estimate")
+
+	// Validate input
+	if !rTimeEstimateStr.MatchString(timeStr) && !rTimeEstimateStrHoursOnly.MatchString(timeStr) {
+		ctx.Flash.Error(ctx.Tr("repo.issues.time_estimate_invalid"))
+		ctx.Redirect(url, http.StatusSeeOther)
+		return
+	}
+
+	total := util.TimeEstimateFromStr(timeStr)
+
+	// User entered something wrong
+	if total == 0 && len(timeStr) != 0 {
+		ctx.Flash.Error(ctx.Tr("repo.issues.time_estimate_invalid"))
+		ctx.Redirect(url, http.StatusSeeOther)
+		return
+	}
+
+	// No time changed
+	if issue.TimeEstimate == total {
+		ctx.Redirect(url, http.StatusSeeOther)
+		return
+	}
+
+	if err := issue_service.ChangeTimeEstimate(issue, ctx.Doer, total); err != nil {
+		ctx.ServerError("ChangeTimeEstimate", err)
+		return
+	}
+
+	ctx.Redirect(url, http.StatusSeeOther)
+}
+
 // UpdateIssueRef change issue's ref (branch)
 func UpdateIssueRef(ctx *context.Context) {
 	issue := GetActionIssue(ctx)

routers/web/repo/issue_timetrack.go

@@ -34,15 +34,15 @@ func AddTimeManually(c *context.Context) {
 		return
 	}
 
-	total := time.Duration(form.Hours)*time.Hour + time.Duration(form.Minutes)*time.Minute
+	total := util.TimeEstimateFromStr(form.TimeString)
 
 	if total <= 0 {
 		c.Flash.Error(c.Tr("repo.issues.add_time_sum_to_small"))
 		c.Redirect(url, http.StatusSeeOther)
 		return
 	}
 
-	if _, err := issues_model.AddTime(c, c.Doer, issue, int64(total.Seconds()), time.Now()); err != nil {
+	if _, err := issues_model.AddTime(c, c.Doer, issue, total, time.Now()); err != nil {
 		c.ServerError("AddTime", err)
 		return
 	}

routers/web/web.go

@@ -1208,6 +1208,7 @@ func registerRoutes(m *web.Route) {
 						m.Post("/cancel", repo.CancelStopwatch)
 					})
 				})
+				m.Post("/time_estimate", repo.UpdateIssueTimeEstimate)
 				m.Post("/reactions/{action}", web.Bind(forms.ReactionForm{}), repo.ChangeIssueReaction)
 				m.Post("/lock", reqRepoIssuesOrPullsWriter, web.Bind(forms.IssueLockForm{}), repo.LockIssue)
 				m.Post("/unlock", reqRepoIssuesOrPullsWriter, repo.UnlockIssue)