From ff68b39c93d7b0d10e0f6629fb188f8f1c0b37d4 Mon Sep 17 00:00:00 2001
From: silverwind <me@silverwind.io>
Date: Sun, 25 Oct 2026 00:36:27 +0200
Subject: [PATCH] docs: update AGENTS.md and dev docs (#39976)

Agents rarely read the `docs` guides when AGENTS.md only asks for
relevant ones. AGENTS.md now names the guide for each area, and rules
agents kept missing go into those guides.

- AGENTS.md maps Go, TS, CSS, Vue, templates, tests, config options,
migrations and refactors to their guide
- The backend guide lists XORM pitfalls behind recent bugs
(https://gitea.com/xorm/xorm/issues/2615): zero-valued struct
conditions, `Cols` and `updated` columns on updates, soft-delete values,
index drops by `SyncAllTables`, MSSQL limits and pagination order
- The development guide requires a `WIP:` companion docs PR copying the
ini text verbatim for `app.example.ini` changes, and says to avoid
migrations unless the alternative is a workaround
---
 AGENTS.md                  |  2 +-
 docs/development.md        |  5 ++++-
 docs/guidelines-backend.md | 13 +++++++++++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7d1b5aa5efb..fb3d5e25559 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 - Never assume, verify before claiming
 - List development targets with `make help`
-- Read relevant developer documentation in the `docs` folder
+- Before working on code, read the `docs` guides for every area touched: `guidelines-backend.md` for Go, `guidelines-frontend.md` for TS, CSS and Vue, both for templates, `testing.md` for tests, `development.md` for config options and migrations, `guidelines-refactoring.md` for refactors
 - PR descriptions: minimal, only what and why, no task or file listings. Include screenshots for UI changes, before and after when modifying existing UI. Aim for less than 1000 characters
 - Reference issues and PRs by full URL, not by number
 - Use Conventional Commits for commit messages and PR titles, plus Gitea's `enhance` type for user-facing enhancements
diff --git a/docs/development.md b/docs/development.md
index 88a0380204a..d2737cffe4b 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -105,10 +105,13 @@ When adding configuration options it is not enough to add them to the
 [`custom/conf/app.example.ini`](../custom/conf/app.example.ini), and document them in
 the [configuration cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet),
 which lives in the [documentation repository](https://gitea.com/gitea/docs).
+Every `app.example.ini` change needs a companion PR there that copies the ini text
+verbatim into every affected version's cheat sheet, translated where feasible, with a
+`WIP:` title prefix until the Gitea PR merges.
 
 ## Database migrations
 
-If you make breaking changes to a database-persisted struct under `models/`, add a
+Avoid migrations unless the alternative is a workaround. If you make breaking changes to a database-persisted struct under `models/`, add a
 new migration in `modelmigration/`. See [testing.md](testing.md#migration-tests)
 for running the migration tests.
 
diff --git a/docs/guidelines-backend.md b/docs/guidelines-backend.md
index 66500ac3914..b46f9214ad1 100644
--- a/docs/guidelines-backend.md
+++ b/docs/guidelines-backend.md
@@ -74,6 +74,19 @@ conditional `UPDATE` or a lock.
   plain `Sync`.
 - When inserting rows with preset IDs, MSSQL requires `SET IDENTITY_INSERT` to be
   enabled and PostgreSQL requires the sequence to be updated afterwards.
+- Struct conditions skip zero-valued fields, so `Get(&Reaction{IssueID: 1})` also
+  matches comment reactions. Use `Where` or `builder` when a zero value matters.
+- Struct updates skip zero-valued fields unless selected by `Cols` or `AllCols()`.
+  `Cols` silently ignores unknown names. `updated` columns are always written unless
+  `NoAutoTime()` is used.
+- `xorm:"deleted"` columns count both `0` and `NULL` as not deleted, so hand-written
+  conditions must accept both.
+- On every start, `SyncAllTables` drops indexes absent from the model, so declare
+  migration-created indexes there, including in backports. It only warns about
+  nullability and default changes, so apply them through migrations.
+- `ForUpdate` only works on MySQL and PostgreSQL. MSSQL rejects TEXT columns in
+  struct conditions and inserts of more than 1000 rows.
+- Paginated queries need a unique tiebreaker like `id` for a stable order.
 
 ## Dependencies