Improve the maintainblity of the reserved username list (#32229)

1 files changed, 29 insertions, 27 deletions

diff --git a/models/user/user.go b/models/user/user.go
index c1e3d5d1c7..c1cb988e43 100644
--- a/models/user/user.go
+++ b/models/user/user.go
@@ -565,41 +565,43 @@ var (
 		".",
 		"..",
 		".well-known",
-		"api",
-		"assets",
-		"attachments",
-		"avatar",
-		"avatars",
+
+		"api",     // gitea api
+		"metrics", // prometheus metrics api
+		"v2",      // container registry api
+
+		"assets",      // static asset files
+		"attachments", // issue attachments
+
+		"avatar",  // avatar by email hash
+		"avatars", // user avatars by file name
+		"repo-avatars",
+
 		"captcha",
-		"commits",
-		"debug",
-		"error",
+		"login", // oauth2 login
+		"org",   // org create/manage, or "/org/{org}", BUT if an org is named as "invite" then it goes wrong
+		"repo",  // repo create/migrate, etc
+		"user",  // user login/activate/settings, etc
+
 		"explore",
-		"favicon.ico",
-		"ghost",
 		"issues",
-		"login",
-		"manifest.json",
-		"metrics",
+		"pulls",
 		"milestones",
-		"new",
 		"notifications",
-		"org",
-		"pulls",
-		"raw",
-		"repo",
-		"repo-avatars",
-		"robots.txt",
-		"search",
-		"serviceworker.js",
-		"ssh_info",
+
+		"favicon.ico",
+		"manifest.json", // web app manifests
+		"robots.txt",    // search engine robots
+		"sitemap.xml",   // search engine sitemap
+		"ssh_info",      // agit info
 		"swagger.v1.json",
-		"user",
-		"v2",
-		"gitea-actions",
+
+		"ghost",         // reserved name for deleted users (id: -1)
+		"gitea-actions", // gitea builtin user (id: -2)
 	}
 
-	// DON'T ADD ANY NEW STUFF, WE SOLVE THIS WITH `/user/{obj}` PATHS!
+	// These names are reserved for user accounts: user's keys, user's rss feed, user's avatar, etc.
+	// DO NOT add any new stuff! The paths with these names are processed by `/{username}` handler (UsernameSubRoute) manually.
 	reservedUserPatterns = []string{"*.keys", "*.gpg", "*.rss", "*.atom", "*.png"}
 )