src: kw patch_track

database/kwdb.sql

@@ -46,6 +46,94 @@ CREATE TABLE IF NOT EXISTS "event" (
   PRIMARY KEY("id")
 );
 
+-- This is the table that holds the events triggered by kw, currently pertains
+-- to the executed commands that are saved and the pomodoro sessions created
+CREATE TABLE IF NOT EXISTS "patch" (
+  "id" INTEGER,
+  "title" TEXT NOT NULL,
+  "author_email" TEXT,
+  "status" VARCHAR(50) DEFAULT ('SENT') NOT NULL,
+  "commit_hash" TEXT,
+  "created_at" TEXT DEFAULT (datetime('now','localtime')),
+  "contribution_id" INTEGER NOT NULL,
+  CHECK ("status" IN ('SENT', 'APPROVED', 'MERGED', 'REVIEWED', 'REJECTED')),
+  PRIMARY KEY("id"),
+  FOREIGN KEY ("contribution_id") REFERENCES "contribution"("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "contribution_tag" (
+  "id" INTEGER,
+  "name" VARCHAR(50) NOT NULL UNIQUE,
+  PRIMARY KEY("id")
+);
+
+CREATE TABLE IF NOT EXISTS "contribution_tag_relation" (
+  "tag_id" INTEGER NOT NULL,
+  "contribution_id" INTEGER NOT NULL,
+  FOREIGN KEY ("tag_id") REFERENCES "patch_tag"("id") ON DELETE CASCADE,
+  FOREIGN KEY ("contribution_id") REFERENCES "contribution"("id") ON DELETE CASCADE,
+  UNIQUE("tag_id", "contribution_id")
+);
+
+CREATE TABLE IF NOT EXISTS "submission" (
+  "id" INTEGER,
+  "contribution_id" INTEGER NOT NULL,
+  "send_by" TEXT NOT NULL,
+  "created_at" TEXT DEFAULT (datetime('now','localtime')),
+  PRIMARY KEY("id"),
+  FOREIGN KEY ("contribution_id") REFERENCES "contribution"("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "patch_submission" (
+  "patch_id" INTEGER NOT NULL,
+  "submission_id" INTEGER NOT NULL,
+  "message_id" TEXT NOT NULL,
+  "created_at" TEXT DEFAULT (datetime('now','localtime')),
+  PRIMARY KEY ("patch_id", "submission_id", "message_id"),
+  FOREIGN KEY ("submission_id") REFERENCES "submission"("id") ON DELETE CASCADE,
+  FOREIGN KEY ("patch_id") REFERENCES "patch"("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "contribution" (
+  "id" INTEGER,
+  "title" TEXT NOT NULL,
+  "created_at" TEXT DEFAULT (datetime('now','localtime')),
+  "last_interaction_at" TEXT DEFAULT (datetime('now','localtime')),
+  "status" VARCHAR(50) DEFAULT ('SENT') NOT NULL,
+  "author_email" TEXT NOT NULL,
+  "repository_id" INTEGER,
+  UNIQUE("title", "author_email")
+  PRIMARY KEY("id"),
+  FOREIGN KEY ("repository_id") REFERENCES "repository"("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "repository" (
+  "id" INTEGER,
+  "created_at" TEXT DEFAULT (datetime('now','localtime')),
+  "name" TEXT NOT NULL,
+  "origin_url" TEXT NOT NULL UNIQUE,
+  PRIMARY KEY("id")
+);
+
+CREATE TABLE IF NOT EXISTS "repository_maintainer" (
+  "id" INTEGER,
+  "repository_id" INTEGER NOT NULL,
+  "contact_id" INTEGER NOT NULL,
+  PRIMARY KEY("id"),
+  UNIQUE ("repository_id", "contact_id"),
+  FOREIGN KEY ("repository_id") REFERENCES "repository"("id") ON DELETE CASCADE,
+  FOREIGN KEY ("contact_id") REFERENCES "email_contact"("id") ON DELETE CASCADE
+);
+
+-- Table containing the kw email contacts infos
+CREATE TABLE IF NOT EXISTS "email_contact" (
+    "id" INTEGER NOT NULL UNIQUE,
+    "name" VARCHAR(100) NOT NULL,
+    "email" VARCHAR(100) NOT NULL UNIQUE,
+    "created_at" TEXT DEFAULT (date('now', 'localtime')),
+    PRIMARY KEY("id")
+);
+
 -- This is the relationship between an "event" that executes a given
 -- "command_label"
 CREATE TABLE IF NOT EXISTS "executed" (

documentation/conf.py

@@ -181,6 +181,7 @@
     ('man/features/kw-self-update', 'kw-self-update', 'kw self-update mechanism', ['David Tadokoro, Everaldo Junior'], 1),
     ('man/features/kw-patch-hub', 'kw-patch-hub', 'Terminal UI to interact with patches from lore.kernel.org', ['David Tadokoro, Rodrigo Siqueira'], 1),
     ('man/features/kw-bd', 'kw-bd', 'build and then deploy the kernel', ['Briza Mel de Sousa, Lorenzo Salvador'], 1),
+    ('man/features/kw-patch-track', 'kw-patch-track', 'track and display patches sent with kw-send-patch', ['João Guilherme Barbosa de Souza'], 1),
 ]
 
 

documentation/dependencies/arch.dependencies

@@ -30,3 +30,6 @@ procps-ng
 pciutils
 libnotify
 python-sphinx
+mutt
+xvfb
+xterm

documentation/dependencies/debian.dependencies

@@ -32,3 +32,7 @@ procps
 pciutils
 libnotify-bin
 python3-sphinx
+mutt
+mutt
+xvfb
+xterm

documentation/dependencies/fedora.dependencies

@@ -28,3 +28,6 @@ procps-ng
 pciutils
 libnotify
 python3-sphinx
+mutt
+xvfb
+xterm

documentation/man/features/kw-patch-track.rst

@@ -0,0 +1,94 @@
+==================================================================
+kw-patch-track - Track and display patches sent with kw-send-patch
+==================================================================
+
+.. _patch-track-doc:
+
+SYNOPSIS
+========
+| *kw patch-track* [OPTIONS]
+
+DESCRIPTION
+===========
+The `kw patch-track` feature manages local tracking of patch submissions sent via 
+`kw send-patch`. It works by scraping metadata from submission logs to populate 
+a local database, keeping record of shipping dates, status, and titles. 
+
+Beyond simple visualization, it provides a heuristic engine to automatically 
+update patch statuses based on mailing list activity and allows for deep 
+integration with the `mutt` email client to facilitate review follow-ups.
+
+OPTIONS
+=======
+--show-patches:
+  Displays the patches dashboard in chronological order, showing patch ID, 
+  creation date, current status, and title.
+
+-d, --show-contributions:
+  Displays the contributions dashboard, grouping sets of patches into higher-level 
+  contribution entities.
+
+-f <YYYY-MM-DD>, --from <YYYY-MM-DD>, -a <YYYY-MM-DD>, --after <YYYY-MM-DD>:
+  Filters the dashboard to display only patches created on or after the specified date.
+
+-b <YYYY-MM-DD>, --before <YYYY-MM-DD>:
+  Filters the dashboard to display only patches created before the specified date.
+
+--id <patch_id>:
+  Specifies a unique patch ID for status modification.
+
+-s <status>, --set-status <status>:
+  Manually sets a new status for a specific patch (specified via --id). 
+  Available statuses: SUBMITTED, REVIEWED, APPROVED, MERGED, REJECTED.
+
+-u, --update:
+  Triggers the automated heuristic engine to update patch statuses by analyzing 
+  associated email threads.
+
+-c <contribution_id>, --contribution-id <contribution_id>:
+  Specifies the contribution ID to be used with repository or mutt operations.
+
+--set-repository <name:url>:
+  Associates a repository name and its origin URL to a contribution. 
+  Requires --contribution-id.
+
+-r <repository_id>, --repository-id <repository_id>:
+  Specifies the repository ID to be used with maintainer operations.
+
+-m <name:email>, --set-maintainer <name:email>:
+  Associates a maintainer's name and email to a specific repository. 
+  Requires --repository-id.
+
+-o, --open-contribution:
+  Opens the email thread associated with a contribution directly in the `mutt` 
+  terminal client. Requires --contribution-id.
+
+EXAMPLES
+========
+To view the chronological dashboard of all patches:
+
+  kw patch-track --show-patches
+
+To view grouped contributions:
+
+  kw patch-track --show-contributions
+
+To filter patches submitted within a specific timeframe:
+
+  kw patch-track --show-patches --after 2023-01-01 --before 2023-12-31
+
+To manually update a patch status after a maintainer's feedback:
+
+  kw patch-track --id 42 --set-status APPROVED
+
+To run the automatic status update heuristics:
+
+  kw patch-track --update
+
+To link a contribution to a specific subsystem repository:
+
+  kw patch-track --contribution-id 10 --set-repository "linux-usb:https://git.kernel.org/..."
+
+To open a specific contribution thread in mutt for review:
+
+  kw patch-track --contribution-id 10 --open-contribution

etc/patch_track_mutt.config

@@ -0,0 +1,8 @@
+# Mutt options to be used with patch-track
+imap_user=
+imap_pass=
+
+folder="imaps://imap.gmail.com"
+spoolfile="+[Gmail]/Todos os e-mails"
+record="+[Gmail]/Sent Mail"
+mbox_type="Maildir"

kw

@@ -15,6 +15,9 @@ KW_DOC_DIR="${KW_SHARE_DIR}/doc"
 KW_MAN_DIR="${KW_SHARE_DIR}/man"
 KW_SOUND_DIR="${KW_SHARE_DIR}/sound"
 KW_DB_DIR="${KW_SHARE_DIR}/database"
+KW_MUTT_DIR="${KW_SHARE_DIR}/mutt"
+KW_MUTT_MESSAGES_DIR="${KW_MUTT_DIR}/messages"
+KW_MUTT_HEADERS_DIR="${KW_MUTT_DIR}/headers"
 
 # Configuration files
 KW_ETC_DIR="${XDG_CONFIG_HOME:-"${HOME}/.config"}/${KWORKFLOW}"
@@ -61,6 +64,9 @@ if [ -f "${KW_BASE_DIR}/src/lib/kwlib.sh" ]; then
   KW_ETC_DIR="${KW_BASE_DIR}/etc"
   KW_PLUGINS_DIR="${KW_LIB_DIR}/plugins"
   KW_SRC_LIB_DIR="${KW_LIB_DIR}/lib"
+  KW_MUTT_DIR="${KW_BASE_DIR}/mutt"
+  KW_MUTT_MESSAGES_DIR="${KW_MUTT_DIR}/messages"
+  KW_MUTT_HEADERS_DIR="${KW_MUTT_DIR}/messages"
   # KW_CACHE_DIR # use default cache folder
 fi
 ##END-REPO-MODE##
@@ -85,6 +91,10 @@ if [[ "${KW_REPO_MODE}" == 'y' ]]; then
   repo_mode_msg+=$'\t'"KW_CACHE_DIR=${KW_CACHE_DIR}"$'\n'
   repo_mode_msg+=$'\t'"KW_DATA_DIR=${KW_DATA_DIR}"$'\n'
   repo_mode_msg+=$'\t'"KW_DB_DIR=${KW_DB_DIR}"$'\n'
+  repo_mode_msg+=$'\t'"KW_MUTT_DIR=${KW_MUTT_DIR}"$'\n'
+  repo_mode_msg+=$'\t'"KW_MUTT_DIR=${KW_MUTT_MESSAGES_DIR}"$'\n'
+  repo_mode_msg+=$'\t'"KW_MUTT_DIR=${KW_MUTT_HEADERS_DIR}"$'\n'
+  repo_mode_msg+=$'\t'"KW_MUTT_MAIL_DIR=${KW_MUTT_MAIL_DIR}"$'\n'
   repo_mode_msg+=$'\t'"KW_DOC_DIR=${KW_DOC_DIR}"$'\n'
   repo_mode_msg+=$'\t'"KW_ETC_DIR=${KW_ETC_DIR}"$'\n'
   repo_mode_msg+=$'\t'"KW_LIB_DIR=${KW_LIB_DIR}"$'\n'
@@ -268,6 +278,13 @@ function kw()
         patch_hub_main "$@"
       )
       ;;
+    patch-track)
+      (
+        include "${KW_LIB_DIR}/patch_track.sh"
+
+        patch_track_main "$@"
+      )
+      ;;
     clear-cache)
       include "${KW_LIB_DIR}/deploy.sh"
 

setup.sh

@@ -31,6 +31,8 @@ declare -r etcdir="${XDG_CONFIG_HOME:-"$HOME/.config"}/$app_name"
 declare -r cachedir="${XDG_CACHE_HOME:-"$HOME/.cache/$app_name"}"
 declare -r tracingdir="${datadir}/tracing"
 declare -r dot_configs_dir="${datadir}/configs"
+declare -r muttdir="${datadir}/mutt"
+declare -r muttmaildir="${muttdir}/mail"
 
 ##
 ## Source code references
@@ -557,6 +559,10 @@ function synchronize_files()
   mkdir -p "$datadir"
   mkdir -p "$datadir/statistics"
   mkdir -p "$datadir/configs"
+
+  mkdir -p "$muttdir"
+  mkdir -p "$muttmaildir"
+
   if [[ -x "${databasedir}/migrate_legacy_data_20220101.sh" ]]; then
     eval "${databasedir}/migrate_legacy_data_20220101.sh"
   else

src/init.sh

@@ -24,6 +24,7 @@ function init_main()
   local mail_name='send_patch.config'
   local notification_name='notification.config'
   local remote_name='remote.config'
+  local patch_track_mutt_name='patch_track_mutt.config'
   local config_file_template
   local deploy_config_file_template
   local remote_file_template
@@ -66,6 +67,7 @@ function init_main()
   mail_config_file_template="${KW_ETC_DIR}/send_patch.config"
   notification_config_file_template="${KW_ETC_DIR}/notification_template.config"
   remote_file_template="${KW_ETC_DIR}/remote.config"
+  patch_track_mutt_config_file_template="${KW_ETC_DIR}/patch_track_mutt.config"
 
   if [[ ! -f "$config_file_template" || ! -f "$build_config_file_template" ]]; then
     complain "No such: ${config_file_template}"
@@ -80,6 +82,8 @@ function init_main()
   cmd_manager "$flag" "cp ${mail_config_file_template} ${PWD}/${KW_DIR}/${mail_name}"
   cmd_manager "$flag" "cp ${notification_config_file_template} ${PWD}/${KW_DIR}/${notification_name}"
   cmd_manager "$flag" "cp ${remote_file_template} ${PWD}/${KW_DIR}/${remote_name}"
+  cmd_manager "$flag" "cp ${patch_track_mutt_config_file_template} ${PWD}/${KW_DIR}/${patch_track_mutt_name}"
+
   cmd_manager "$flag" "sed --in-place --expression \"s/USERKW/${USER}/g\" -e '/^#?.*/d' ${PWD}/${KW_DIR}/${vm_name}"
   cmd_manager "$flag" "sed --in-place --expression \"s,SOUNDPATH,${KW_SOUND_DIR},g\" -e '/^#?.*/d' ${PWD}/${KW_DIR}/${notification_name}"
 

src/lib/kw_config_loader.sh

@@ -8,6 +8,8 @@ DEPLOY_CONFIG_FILENAME='deploy.config'
 VM_CONFIG_FILENAME='vm.config'
 SEND_PATCH_CONFIG_FILENAME='send_patch.config'
 SEND_PATCH_CONFIG_FILENAME='lore.config'
+PATCH_TRACK_MUTT_CONFIG_FILENAME='patch_track_mutt.config'
+
 KW_DIR='.kw'
 
 # Basic targets
@@ -53,6 +55,11 @@ declare -gA lore_config
 declare -gA lore_config_global
 declare -gA lore_config_local
 
+# Notification configuration
+declare -gA patch_track_mutt_config
+declare -gA patch_track_mutt_config_global
+declare -gA patch_track_mutt_config_local
+
 # Default target option from kworkflow.config
 declare -gA deploy_target_opt=(['local']=2 ['remote']=3)
 
@@ -325,12 +332,16 @@ function load_configuration()
     'lore')
       target_array='lore_config'
       ;;
+    'patch_track_mutt')
+      target_array='patch_track_mutt_config'
+      ;;
   esac
 
   target_array_global="${target_array}_global"
   target_array_local="${target_array}_local"
 
   target_config_file="${target_config}.config"
+
   parse_configuration "${KW_ETC_DIR}/${target_config_file}" "$target_array" "$target_array_global"
 
   # XDG_CONFIG_DIRS is a colon-separated list of directories for config
@@ -399,6 +410,11 @@ load_lore_config()
   load_configuration 'lore'
 }
 
+load_patch_track_mutt_config()
+{
+  load_configuration 'patch_track_mutt'
+}
+
 load_all_config()
 {
   load_notification_config
@@ -408,4 +424,5 @@ load_all_config()
   load_send_patch_config
   load_lore_config
   load_vm_config
+  load_patch_track_mutt_config
 }