> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daycopilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft/Publish Workflow

> Understanding Day Copilot's versioning system for collaborative editing

## Overview

Day Copilot implements a **draft/publish workflow** that allows you to make changes to tasks and events without immediately affecting the published version. This is particularly useful for collaborative editing, review processes, and preventing accidental changes.

<Note>
  The draft/publish workflow is optional. Simple updates (status changes, adding comments) can bypass drafting if needed.
</Note>

## How It Works

### Version Numbers

Every task and event has two version numbers:

| Property        | Description                        |
| --------------- | ---------------------------------- |
| `version_major` | Published version (e.g., 1, 2, 3)  |
| `version_minor` | Draft version (e.g., 1, 2, 3)      |
| `is_published`  | Whether current state is published |

**Example:**

```json theme={null}
{
  "id": "task-uuid",
  "title": "Complete API documentation",
  "version_major": 2,
  "version_minor": 3,
  "is_published": false
}
```

This means:

* **Published version**: 2.0 (last accepted state)
* **Draft version**: 2.3 (current working state with 3 edits)
* **Status**: Unpublished (changes not yet live)

### State Machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> Published_v1.0
    Published_v1.0 --> Draft_v1.1: Make changes
    Draft_v1.1 --> Draft_v1.2: More changes
    Draft_v1.2 --> Published_v2.0: Accept draft
    Draft_v1.2 --> Published_v1.0: Discard draft
    Published_v2.0 --> Draft_v2.1: Make new changes
```

## Creating a Draft

When you update a published task or event, it automatically becomes a draft:

### Example: Update Task

```bash theme={null}
PUT /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000
{
  "title": "Complete comprehensive API documentation",
  "priority": "urgent"
}
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete comprehensive API documentation",
    "priority": "urgent",
    "version_major": 1,
    "version_minor": 2,
    "is_published": false,
    "last_live": {
      "title": "Complete API documentation",
      "priority": "high",
      "version": "1.0"
    }
  }
}
```

**What Happened:**

1. Task was at version 1.0 (published)
2. Your update created version 1.2 (draft)
3. `last_live` contains the snapshot of version 1.0
4. Changes are not yet published

## Publishing a Draft

To make your draft changes official, publish the draft:

```bash theme={null}
POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/draft
{
  "action": "accept"
}
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete comprehensive API documentation",
    "priority": "urgent",
    "version_major": 2,
    "version_minor": 0,
    "is_published": true,
    "last_live": null
  }
}
```

**What Happened:**

1. Draft version 1.2 became published version 2.0
2. `is_published` set to `true`
3. `last_live` cleared (no longer needed)
4. Ready for new edits

## Discarding a Draft

To revert to the last published version:

```bash theme={null}
POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/draft
{
  "action": "discard"
}
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Complete API documentation",
    "priority": "high",
    "version_major": 1,
    "version_minor": 0,
    "is_published": true,
    "last_live": null
  }
}
```

**What Happened:**

1. Draft changes discarded
2. Reverted to last published state (version 1.0)
3. All unpublished edits lost

## Use Cases

### 1. Review Process

```mermaid theme={null}
sequenceDiagram
    participant User
    participant API
    participant Reviewer

    User->>API: PUT /tasks/{id} (changes)
    API-->>User: Draft v1.1 created
    User->>API: PUT /tasks/{id} (more changes)
    API-->>User: Draft v1.2 updated
    User->>Reviewer: Request review

    alt Approved
        Reviewer->>API: POST /draft (accept)
        API-->>Reviewer: Published as v2.0
    else Rejected
        Reviewer->>API: POST /draft (discard)
        API-->>Reviewer: Reverted to v1.0
    end
```

**Example Workflow:**

1. Developer updates task description (creates draft)
2. Adds code examples (draft v1.2)
3. Asks manager to review
4. Manager approves → publish draft
5. OR manager rejects → discard draft

### 2. Batch Editing

Make multiple changes without notifying collaborators until ready:

```javascript theme={null}
// Make several changes
await updateTask(taskId, { priority: 'high' });      // Draft v1.1
await updateTask(taskId, { due_date: tomorrow });    // Draft v1.2
await updateTask(taskId, { description: '...' });    // Draft v1.3

// Publish all at once
await publishDraft(taskId);  // All changes go live as v2.0
```

### 3. Conflict Prevention

Two users editing the same task:

```mermaid theme={null}
sequenceDiagram
    participant Alice
    participant API
    participant Bob

    Note over Alice,Bob: Both start with v1.0

    Alice->>API: PUT /tasks/{id} (change A)
    API-->>Alice: Draft v1.1

    Bob->>API: PUT /tasks/{id} (change B)
    API-->>Bob: Draft v1.1 (new branch)

    Alice->>API: POST /draft (accept)
    API-->>Alice: Published as v2.0

    Bob->>API: POST /draft (accept)
    API-->>Bob: Error: Conflict detected
```

<Warning>
  When multiple users create drafts, only one can be published. The second will receive a conflict error and must rebase their changes.
</Warning>

## Bypassing the Draft Workflow

Some operations don't require drafting:

### Status Changes

```bash theme={null}
POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/complete
```

This directly publishes the status change without creating a draft.

### Adding Comments

```bash theme={null}
POST /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/comments
{
  "message": "Great progress!"
}
```

Comments are always immediately visible, no drafting.

### Quick Updates

Include `publish: true` in update requests:

```bash theme={null}
PUT /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000
{
  "priority": "urgent",
  "publish": true
}
```

This creates and immediately publishes the draft in one operation.

## Querying Drafts

### Get Only Published Items

```bash theme={null}
GET /api/v1/tasks?published=true
```

### Get Only Drafts

```bash theme={null}
GET /api/v1/tasks?published=false
```

### Include Draft Status

```bash theme={null}
GET /api/v1/tasks?include_draft_status=true
```

Response includes draft information:

```json theme={null}
{
  "data": [
    {
      "id": "task-1",
      "is_published": true,
      "version_major": 3,
      "version_minor": 0
    },
    {
      "id": "task-2",
      "is_published": false,
      "version_major": 1,
      "version_minor": 2,
      "has_unpublished_changes": true
    }
  ]
}
```

## Version History

Access previous versions:

```bash theme={null}
GET /api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/history
```

Response:

```json theme={null}
{
  "data": {
    "current": {
      "version": "2.3",
      "is_published": false,
      "updated_at": "2025-11-02T15:00:00Z"
    },
    "published": {
      "version": "2.0",
      "updated_at": "2025-11-01T10:00:00Z",
      "snapshot": { ... }
    },
    "history": [
      {
        "version": "1.0",
        "published_at": "2025-10-15T12:00:00Z"
      }
    ]
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Publish Frequently">
    Don't leave drafts unpublished for extended periods. This can cause sync issues with collaborators.
  </Accordion>

  <Accordion title="Use Drafts for Major Changes">
    Use the draft workflow for significant updates that benefit from review. Skip it for minor changes like status updates.
  </Accordion>

  <Accordion title="Handle Conflicts Gracefully">
    When publish fails due to conflicts, fetch the latest published version, merge changes manually, and republish.
  </Accordion>

  <Accordion title="Communicate Draft Status">
    In UI, clearly indicate when viewing a draft vs published version to avoid confusion.
  </Accordion>
</AccordionGroup>

## Error Handling

### Conflict Error

```json theme={null}
{
  "error": "Draft conflict",
  "message": "Another draft was published while yours was being edited",
  "status": 409,
  "data": {
    "your_version": "1.2",
    "current_version": "2.0",
    "conflicting_fields": ["title", "priority"]
  }
}
```

**Resolution:**

1. Fetch latest published version (`GET /tasks/{id}`)
2. Merge your changes with current state
3. Create new draft with merged changes
4. Publish

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Tasks Guide" icon="list-check" href="/guides/managing-tasks">
    See draft workflow in action
  </Card>

  <Card title="Tasks & Events Model" icon="database" href="/concepts/tasks-events-contexts">
    Understand the data model
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tasks/update">
    Explore draft endpoints
  </Card>

  <Card title="Error Handling Guide" icon="triangle-exclamation" href="/guides/error-handling">
    Handle conflicts and errors
  </Card>
</CardGroup>