Attachments

Attachment Versioning

imdone-cli handles attachment modifications safely to avoid permission errors when working with files created by other team members.

How It Works

Jira: When you modify an attachment that was created by another user:

• A new version is uploaded (no 403 errors)
• The old version is preserved in Jira (not deleted)
• Your local filesystem only keeps the current version
• Metadata tracks all versions for reference

GitHub: When you modify an attachment:

• The stable branch-backed file is updated at _imdone-attachments/{issue}/plan.md
• GitHub’s content SHA is used to detect stale writes
• Your local file stays at ./attachments/plan.md

Multiple Versions

If multiple team members modify the same attachment:

• Jira: Each upload creates a new version; all versions are visible in the Jira UI; on pull, only the most recent version is downloaded locally
• GitHub: The stable branch path is updated with SHA protection. If another user changed the file first, GitHub rejects the stale write instead of silently overwriting it

Deleted and Renamed Attachments

Team Sync:

When you delete or rename an attachment, imdone keeps each provider’s current attachment set aligned:

When you delete an attachment locally:

rm attachments/old-doc.pdf
imdone push

• The file is removed from your local filesystem
• Jira: The attachment remains in Jira (no delete attempt — avoids 403 errors)
• GitHub: The stable branch path is deleted from imdone-attachments
• Jira deletes are added to your local ignored list so they won’t be re-downloaded on pull
• GitHub deletes disappear from the branch current set, so team members stop pulling the old file

When you rename an attachment:

mv attachments/doc.pdf attachments/doc-v2.pdf
imdone push

• New attachment doc-v2.pdf is uploaded
• Jira: Old attachment doc.pdf remains in Jira and the old name is added to your ignored list
• GitHub: Old branch path doc.pdf is deleted and the new branch path doc-v2.pdf becomes current
• Team members pull the provider’s current attachment set

Automatic Synchronization:

When any team member runs imdone pull:

1. Jira comments are parsed for delete/rename events where Jira needs the ignored-list workflow
2. GitHub reads the current attachment files from the imdone-attachments branch
3. Only current attachments are downloaded
4. Everyone stays in sync automatically

Manual Cleanup

Old Jira versions are not automatically deleted from Jira. This prevents:

• Permission errors (no delete permission needed)
• Accidental data loss
• Team conflicts over attachment ownership

To clean up old versions:

• Jira: Manually delete old attachment versions from the Jira UI
• GitHub: Current attachments are the files present under _imdone-attachments/{issue}/; rename/delete cleanup removes old stable paths automatically

Metadata Format

Attachments are tracked in attachments/.metadata.yml with a filename-keyed structure:

attachments:
  document.pdf:
    current: "12346"  # Most recent version ID
    versions:
      - id: "12346"
        filename: "document.pdf"
        size: 1500
        created: "2025-01-16T14:00:00Z"
        author:
          displayName: "User B"
          accountId: "..."
      - id: "12345"
        filename: "document.pdf"
        size: 1000
        created: "2025-01-15T10:00:00Z"
        author:
          displayName: "User A"
          accountId: "..."
ignored:
  - id: "12347"
    filename: "old-file.png"
    reason: "deleted"
    author: "user@example.com"
    timestamp: "2025-02-25T10:00:00Z"

Auto-migration: Old metadata formats are automatically migrated to the new format on first use. No data loss occurs during migration.