feat(description): add deployment version descriptions

apps/docs/content/docs/en/quick-reference/index.mdx

@@ -335,6 +335,11 @@ A quick lookup for everyday actions in the Sim workflow editor. For keyboard sho
       <td>Access previous versions in Deploy tab → **Promote to live**</td>
       <td><ActionImage src="/static/quick-reference/promote-deployment.png" alt="Promote deployment to live" /></td>
     </tr>
+    <tr>
+      <td>Add version description</td>
+      <td>Deploy tab → Click description icon → Add or generate description</td>
+      <td><ActionVideo src="quick-reference/deployment-description.mp4" alt="Add deployment version description" /></td>
+    </tr>
     <tr>
       <td>Copy API endpoint</td>
       <td>Deploy tab → API → Copy API cURL</td>

apps/sim/app/api/workflows/[id]/deployments/[version]/route.ts

@@ -9,13 +9,24 @@ import { createErrorResponse, createSuccessResponse } from '@/app/api/workflows/
 
 const logger = createLogger('WorkflowDeploymentVersionAPI')
 
-const patchBodySchema = z.object({
-  name: z
-    .string()
-    .trim()
-    .min(1, 'Name cannot be empty')
-    .max(100, 'Name must be 100 characters or less'),
-})
+const patchBodySchema = z
+  .object({
+    name: z
+      .string()
+      .trim()
+      .min(1, 'Name cannot be empty')
+      .max(100, 'Name must be 100 characters or less')
+      .optional(),
+    description: z
+      .string()
+      .trim()
+      .max(500, 'Description must be 500 characters or less')
+      .nullable()
+      .optional(),
+  })
+  .refine((data) => data.name !== undefined || data.description !== undefined, {
+    message: 'At least one of name or description must be provided',
+  })
 
 export const dynamic = 'force-dynamic'
 export const runtime = 'nodejs'
@@ -88,33 +99,46 @@ export async function PATCH(
       return createErrorResponse(validation.error.errors[0]?.message || 'Invalid request body', 400)
     }
 
-    const { name } = validation.data
+    const { name, description } = validation.data
+
+    const updateData: { name?: string; description?: string | null } = {}
+    if (name !== undefined) {
+      updateData.name = name
+    }
+    if (description !== undefined) {
+      updateData.description = description
+    }
 
     const [updated] = await db
       .update(workflowDeploymentVersion)
-      .set({ name })
+      .set(updateData)
       .where(
         and(
           eq(workflowDeploymentVersion.workflowId, id),
           eq(workflowDeploymentVersion.version, versionNum)
         )
       )
-      .returning({ id: workflowDeploymentVersion.id, name: workflowDeploymentVersion.name })
+      .returning({
+        id: workflowDeploymentVersion.id,
+        name: workflowDeploymentVersion.name,
+        description: workflowDeploymentVersion.description,
+      })
 
     if (!updated) {
       return createErrorResponse('Deployment version not found', 404)
     }
 
-    logger.info(
-      `[${requestId}] Renamed deployment version ${version} for workflow ${id} to "${name}"`
-    )
+    logger.info(`[${requestId}] Updated deployment version ${version} for workflow ${id}`, {
+      name: updateData.name,
+      description: updateData.description,
+    })
 
-    return createSuccessResponse({ name: updated.name })
+    return createSuccessResponse({ name: updated.name, description: updated.description })
   } catch (error: any) {
     logger.error(
-      `[${requestId}] Error renaming deployment version ${version} for workflow ${id}`,
+      `[${requestId}] Error updating deployment version ${version} for workflow ${id}`,
       error
     )
-    return createErrorResponse(error.message || 'Failed to rename deployment version', 500)
+    return createErrorResponse(error.message || 'Failed to update deployment version', 500)
   }
 }

apps/sim/app/api/workflows/[id]/deployments/route.ts

@@ -26,6 +26,7 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
         id: workflowDeploymentVersion.id,
         version: workflowDeploymentVersion.version,
         name: workflowDeploymentVersion.name,
+        description: workflowDeploymentVersion.description,
         isActive: workflowDeploymentVersion.isActive,
         createdAt: workflowDeploymentVersion.createdAt,
         createdBy: workflowDeploymentVersion.createdBy,

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/general/components/version-description-modal.tsx

@@ -0,0 +1,170 @@
+'use client'
+
+import { useCallback, useRef, useState } from 'react'
+import {
+  Button,
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+  Textarea,
+} from '@/components/emcn'
+import {
+  useGenerateVersionDescription,
+  useUpdateDeploymentVersion,
+} from '@/hooks/queries/deployments'
+
+interface VersionDescriptionModalProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  workflowId: string
+  version: number
+  versionName: string
+  currentDescription: string | null | undefined
+}
+
+export function VersionDescriptionModal({
+  open,
+  onOpenChange,
+  workflowId,
+  version,
+  versionName,
+  currentDescription,
+}: VersionDescriptionModalProps) {
+  const initialDescriptionRef = useRef(currentDescription || '')
+  const [description, setDescription] = useState(initialDescriptionRef.current)
+  const [showUnsavedChangesAlert, setShowUnsavedChangesAlert] = useState(false)
+
+  const updateMutation = useUpdateDeploymentVersion()
+  const generateMutation = useGenerateVersionDescription()
+
+  const hasChanges = description.trim() !== initialDescriptionRef.current.trim()
+  const isGenerating = generateMutation.isPending
+
+  const handleCloseAttempt = useCallback(() => {
+    if (updateMutation.isPending || isGenerating) {
+      return
+    }
+    if (hasChanges) {
+      setShowUnsavedChangesAlert(true)
+    } else {
+      onOpenChange(false)
+    }
+  }, [hasChanges, updateMutation.isPending, isGenerating, onOpenChange])
+
+  const handleDiscardChanges = useCallback(() => {
+    setShowUnsavedChangesAlert(false)
+    setDescription(initialDescriptionRef.current)
+    onOpenChange(false)
+  }, [onOpenChange])
+
+  const handleGenerateDescription = useCallback(() => {
+    generateMutation.mutate({
+      workflowId,
+      version,
+      onStreamChunk: (accumulated) => {
+        setDescription(accumulated)
+      },
+    })
+  }, [workflowId, version, generateMutation])
+
+  const handleSave = useCallback(() => {
+    if (!workflowId) return
+
+    updateMutation.mutate(
+      {
+        workflowId,
+        version,
+        description: description.trim() || null,
+      },
+      {
+        onSuccess: () => {
+          onOpenChange(false)
+        },
+      }
+    )
+  }, [workflowId, version, description, updateMutation, onOpenChange])
+
+  return (
+    <>
+      <Modal open={open} onOpenChange={(openState) => !openState && handleCloseAttempt()}>
+        <ModalContent className='max-w-[480px]'>
+          <ModalHeader>
+            <span>Version Description</span>
+          </ModalHeader>
+          <ModalBody className='space-y-[10px]'>
+            <div className='flex items-center justify-between'>
+              <p className='text-[12px] text-[var(--text-secondary)]'>
+                {currentDescription ? 'Edit the' : 'Add a'} description for{' '}
+                <span className='font-medium text-[var(--text-primary)]'>{versionName}</span>
+              </p>
+              <Button
+                variant='active'
+                className='-my-1 h-5 px-2 py-0 text-[11px]'
+                onClick={handleGenerateDescription}
+                disabled={isGenerating || updateMutation.isPending}
+              >
+                {isGenerating ? 'Generating...' : 'Generate'}
+              </Button>
+            </div>
+            <Textarea
+              placeholder='Describe the changes in this deployment version...'
+              className='min-h-[120px] resize-none'
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              maxLength={500}
+              disabled={isGenerating}
+            />
+            <div className='flex items-center justify-between'>
+              {(updateMutation.error || generateMutation.error) && (
+                <p className='text-[12px] text-[var(--text-error)]'>
+                  {updateMutation.error?.message || generateMutation.error?.message}
+                </p>
+              )}
+              {!updateMutation.error && !generateMutation.error && <div />}
+              <p className='text-[11px] text-[var(--text-tertiary)]'>{description.length}/500</p>
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <Button
+              variant='default'
+              onClick={handleCloseAttempt}
+              disabled={updateMutation.isPending || isGenerating}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant='tertiary'
+              onClick={handleSave}
+              disabled={updateMutation.isPending || isGenerating || !hasChanges}
+            >
+              {updateMutation.isPending ? 'Saving...' : 'Save'}
+            </Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+
+      <Modal open={showUnsavedChangesAlert} onOpenChange={setShowUnsavedChangesAlert}>
+        <ModalContent className='max-w-[400px]'>
+          <ModalHeader>
+            <span>Unsaved Changes</span>
+          </ModalHeader>
+          <ModalBody>
+            <p className='text-[14px] text-[var(--text-secondary)]'>
+              You have unsaved changes. Are you sure you want to discard them?
+            </p>
+          </ModalBody>
+          <ModalFooter>
+            <Button variant='default' onClick={() => setShowUnsavedChangesAlert(false)}>
+              Keep Editing
+            </Button>
+            <Button variant='destructive' onClick={handleDiscardChanges}>
+              Discard Changes
+            </Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  )
+}