From: Simon Glass <sjg@chromium.org>
Document the SQLite database schema in patman.rst including all tables,
columns, types, foreign key relationships and the schema version each
column is added in. This covers the full schema at v10 with series,
ser_ver, pcommit, review, upstream, patchwork, workflow and
schema_version tables.
Signed-off-by: Simon Glass <sjg@chromium.org>
---
tools/patman/patman.rst | 214 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 213 insertions(+), 1 deletion(-)
--
2.43.0
@@ -1268,7 +1268,7 @@ Use ``-n`` with ``--create-drafts`` for a dry run that shows what would
be created without calling the Gmail API.
Use ``--apply-only`` to download and apply patches without running the
-AI review — useful for checking that patches apply cleanly.
+AI review - useful for checking that patches apply cleanly.
Use ``-f`` / ``--force`` to re-review a series that has already been
reviewed. This deletes the old review records and runs the review
@@ -1395,3 +1395,215 @@ Aliases
The ``review`` command supports aliases ``r`` and ``rev``::
patman r -l 497923 -U us --reviewer 'Your Name <your@email>'
+
+
+Database schema
+===============
+
+Patman stores series tracking, review and workflow state in a SQLite
+database (``.patman.db``) in the top-level git directory. The schema is
+versioned and auto-migrated on startup (currently at v10).
+
+The database allows patman to track a patch series across multiple
+versions, recording which patches belong to each version and how they
+map to patchwork entries. This means patman can detect when a new
+version of a series arrives, carry forward review tags and change logs
+from earlier versions, and show upstream progress without re-querying
+patchwork each time.
+
+For AI-assisted review of other people's patches, the database stores
+the generated review text, Gmail draft IDs and thread state so that
+patman can resume where it left off - showing stored reviews, creating
+drafts for reviews that were not yet sent, detecting when drafts have
+been sent or deleted, and providing previous review context when a new
+version of the series is posted. Review-handling notes from the
+``handle-reviews`` workflow are also stored per-version so the AI has
+context about what was changed and why.
+
+Entity relationships
+--------------------
+
+::
+
+ upstream 1---* patchwork (patchwork.upstream references
+ upstream.name)
+
+ series 1---* ser_ver (ser_ver.series_id -> series.id)
+
+ ser_ver 1---* pcommit (pcommit.svid -> ser_ver.id)
+
+ ser_ver 1---* review (review.svid -> ser_ver.id)
+
+ series 1---* workflow (workflow.series_id -> series.id)
+
+A **series** represents a named patch series across all its versions.
+Each **ser_ver** is one version of that series (e.g. v1, v2), linked to
+patchwork by a series link. Each ser_ver has one **pcommit** per patch
+and zero or more **review** records (one per AI review).
+
+Tables
+------
+
+series
+~~~~~~
+
+Patman tracks series that you are working on so it can keep an eye on
+any feedback from other people (from patchwork). Series that are being
+reviewed (other people's patches) are also stored here with
+``source='review'``.
+
+========== ======== ==========================================
+Column Type Description
+========== ======== ==========================================
+id INTEGER Primary key (auto-increment)
+name TEXT Series name (unique)
+desc TEXT Series description / cover-letter title
+archived BIT True if series is archived
+upstream TEXT Upstream name (added v5)
+source TEXT 'review' for AI-reviewed series (added v8)
+========== ======== ==========================================
+
+ser_ver
+~~~~~~~
+
+Each time you send a new version of a series, patman creates a ser_ver
+record linking it to patchwork. This lets patman track review tags,
+change logs and upstream progress separately for each version. For
+AI-reviewed series, review-handling notes are stored here so the next
+version has context about what was changed.
+
+================== ======== ==========================================
+Column Type Description
+================== ======== ==========================================
+id INTEGER Primary key (auto-increment)
+series_id INTEGER FK -> series.id
+version INTEGER Version number (1, 2, ...)
+link TEXT Patchwork series link/ID
+cover_id INTEGER Patchwork cover letter ID (added v3)
+cover_num_comments INTEGER Number of comments on cover (added v3)
+name TEXT Cover letter name (added v3)
+archive_tag TEXT Git tag for archived version (added v4)
+desc TEXT Version description (added v6)
+notes TEXT Review-handling notes (added v10)
+================== ======== ==========================================
+
+pcommit
+~~~~~~~
+
+Each patch in a series version gets a pcommit record. Patman uses the
+Change-Id to match patches across versions (so it knows which patch in
+v2 corresponds to which patch in v1) and tracks the patchwork state and
+comment count so ``patman series progress`` can show upstream status.
+
+============== ======== ==========================================
+Column Type Description
+============== ======== ==========================================
+id INTEGER Primary key (auto-increment)
+svid INTEGER FK -> ser_ver.id
+seq INTEGER Patch sequence (0-based)
+subject TEXT Patch subject line
+patch_id INTEGER Patchwork patch ID
+change_id TEXT Change-Id tag value
+state TEXT Patchwork state (e.g. 'new', 'accepted')
+num_comments INTEGER Number of patchwork comments
+============== ======== ==========================================
+
+review
+~~~~~~
+
+When patman reviews someone else's patches, it stores the generated
+review email text here - one record per patch plus optionally the cover
+letter. This allows patman to show the review again later, create Gmail
+drafts from stored reviews, detect when drafts have been sent or
+deleted, and provide the previous review as context when a new version
+of the series arrives. When ``--sync`` detects that a draft was sent,
+the body is updated to the final text the user actually sent (after any
+manual edits), so the stored review reflects what was really posted to
+the mailing list.
+
+================ ======== ==========================================
+Column Type Description
+================ ======== ==========================================
+id INTEGER Primary key (auto-increment)
+svid INTEGER FK -> ser_ver.id
+seq INTEGER Patch sequence (0=cover, 1..N=patches)
+body TEXT Review email body text
+approved BIT True if Reviewed-by was given
+timestamp TEXT ISO datetime of review creation
+draft_id TEXT Gmail draft ID (added v9)
+status TEXT 'new', 'draft', 'sent', 'deleted',
+ 'replied' (added v9)
+gmail_msg_id TEXT Gmail message ID after sending (added v9)
+gmail_thread_id TEXT Gmail thread ID for replies (added v9)
+================ ======== ==========================================
+
+upstream
+~~~~~~~~
+
+Patman needs to know about the upstream repositories you send patches
+to. Each upstream has a git remote name, URL and optional patchwork
+settings. One upstream can be marked as the default so you do not need
+to specify ``-U`` on every command.
+
+================ ======== ==========================================
+Column Type Description
+================ ======== ==========================================
+name TEXT Git remote name (unique, e.g. 'us')
+url TEXT Repository URL
+is_default BIT True if this is the default upstream
+patchwork_url TEXT Patchwork server URL (added v6)
+identity TEXT Git sendemail identity (added v6)
+series_to TEXT Default To: alias for series (added v6)
+no_maintainers BIT Skip get_maintainer.pl (added v6)
+no_tags BIT Skip subject-tag processing (added v6)
+================ ======== ==========================================
+
+patchwork
+~~~~~~~~~
+
+Each upstream can have a patchwork project associated with it. This
+stores the project name, ID and link name so patman can query patchwork
+for series status, review tags and comments. Multiple upstreams can
+point to different patchwork projects (e.g. U-Boot mainline vs a
+custodian tree).
+
+============== ======== ==========================================
+Column Type Description
+============== ======== ==========================================
+name TEXT Project name (e.g. 'U-Boot')
+proj_id INTEGER Patchwork project ID
+link_name TEXT Patchwork link name (e.g. 'uboot')
+upstream TEXT Upstream name, or NULL for default
+============== ======== ==========================================
+
+workflow
+~~~~~~~~
+
+Patman records workflow events such as when a series was sent, when
+review feedback arrived and what needs attention. The ``patman workflow
+todo`` command uses this to show outstanding tasks across all your
+series.
+
+============== ======== ==========================================
+Column Type Description
+============== ======== ==========================================
+id INTEGER Primary key (auto-increment)
+series_id INTEGER FK -> series.id
+action TEXT Workflow action (e.g. 'sent', 'todo')
+timestamp TEXT ISO datetime
+data TEXT JSON payload
+ser_ver_id INTEGER FK -> ser_ver.id (added v7b)
+============== ======== ==========================================
+
+schema_version
+~~~~~~~~~~~~~~
+
+A single-row table that records which schema version the database is at.
+Patman checks this on startup and runs any needed migrations
+automatically.
+
+============== ======== ==========================================
+Column Type Description
+============== ======== ==========================================
+version INTEGER Current schema version (currently 10)
+============== ======== ==========================================