From 0593b58ff77c1ec4afae519c3d091ee45fbcbf90 Mon Sep 17 00:00:00 2001
From: wxiaoguang <wxiaoguang@gmail.com>
Date: Tue, 14 Apr 2026 04:01:29 +0800
Subject: [PATCH] Add comment for the design of "user activity time" (#37195)

---
 models/activities/user_heatmap.go | 1 +
 services/feed/notifier.go         | 7 ++++++-
 templates/user/heatmap.tmpl       | 1 +
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/models/activities/user_heatmap.go b/models/activities/user_heatmap.go
index e24d44c519..2d1635917e 100644
--- a/models/activities/user_heatmap.go
+++ b/models/activities/user_heatmap.go
@@ -62,6 +62,7 @@ func getUserHeatmapData(ctx context.Context, user *user_model.User, team *organi
 		return nil, err
 	}
 
+	// HINT: USER-ACTIVITY-PUSH-COMMITS: it only uses the doer's action time, it doesn't use git commit's time
 	return hdata, db.GetEngine(ctx).
 		Select(groupBy+" AS timestamp, count(user_id) as contributions").
 		Table("action").
diff --git a/services/feed/notifier.go b/services/feed/notifier.go
index 64aeccdfd2..c0de4d02de 100644
--- a/services/feed/notifier.go
+++ b/services/feed/notifier.go
@@ -327,7 +327,7 @@ func (a *actionNotifier) PushCommits(ctx context.Context, pusher *user_model.Use
 
 	opType := activities_model.ActionCommitRepo
 
-	// Check it's tag push or branch.
+	// Check its tag push or branch.
 	if opts.RefFullName.IsTag() {
 		opType = activities_model.ActionPushTag
 		if opts.IsDelRef() {
@@ -337,6 +337,11 @@ func (a *actionNotifier) PushCommits(ctx context.Context, pusher *user_model.Use
 		opType = activities_model.ActionDeleteBranch
 	}
 
+	// HINT: USER-ACTIVITY-PUSH-COMMITS: it's said that the time of push commits (for user activity display) is designed this way,
+	// it doesn't use git commit's time, it only uses the doer's action time.
+	// ref: https://github.com/go-gitea/gitea/pull/36469#issuecomment-3901955347
+	// ref: https://github.com/go-gitea/gitea/issues/14051
+	// ref: https://github.com/go-gitea/gitea/issues/11861#issuecomment-643162143
 	if err = NotifyWatchers(ctx, &activities_model.Action{
 		ActUserID: pusher.ID,
 		ActUser:   pusher,
diff --git a/templates/user/heatmap.tmpl b/templates/user/heatmap.tmpl
index 22368e78c1..0205611886 100644
--- a/templates/user/heatmap.tmpl
+++ b/templates/user/heatmap.tmpl
@@ -1,4 +1,5 @@
 {{if .EnableHeatmap}}
+{{/*HINT: USER-ACTIVITY-PUSH-COMMITS: it only uses the doer's action time, it doesn't use git commit's time */}}
 <div class="activity-heatmap-container">
 	<div id="user-heatmap" class="is-loading"
 		data-heatmap-url="{{.HeatmapURL}}"