Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/ai/pi-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ Manage your projects:
- Create new projects with descriptions.
- Update project details (name, description, identifier, cover image).
- Delete projects.
- Enable or disable project features (Epics, Cycles, Modules, Pages, Views).
- Enable or disable project features (Cycles, Modules, Pages, Views).

_Example commands:_

Expand Down Expand Up @@ -299,7 +299,7 @@ Align work with strategic goals:
- Create, update, or delete initiative-specific labels.
- Attach or remove labels from initiatives.
- Link or unlink projects to initiatives.
- Link or unlink epics to initiatives.
- Link or unlink work items to initiatives.

_Example commands:_

Expand Down
3 changes: 1 addition & 2 deletions docs/communication-and-collaboration/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,7 @@ Inbox notifications always come through regardless of these settings. These togg
| Work item relation added or removed (blocked by, duplicate, etc.) | Yes |
| Work item deleted | Yes |
| @mention in description or comment | Yes (mention notification) |
| Epic field updated | Yes |
| Epic update published (progress or status post) | Yes — all epic subscribers get an email |
| Work item update published (progress or status post) | Yes — all work item subscribers get an email |
| Due date approaching (reminder) | Yes — subscribers and assignees get an in-app and email notification |

## Notification channels
Expand Down
16 changes: 2 additions & 14 deletions docs/communication-and-collaboration/subscribers.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Subscribers
description: Learn how to subscribe to work items and epics in Plane, manage subscriber lists, set up project-level auto-subscriptions, and understand how Plane subscribes you automatically.
description: Learn how to subscribe to work items in Plane, manage subscriber lists, set up project-level auto-subscriptions, and understand how Plane subscribes you automatically.
---

# Subscribers

A subscription is how you tell Plane to keep you in the loop on a work item or epic. When you're subscribed, you get notified whenever something changes — a state update, a new comment, a priority shift, an assignee change.
A subscription is how you tell Plane to keep you in the loop on a work item. When you're subscribed, you get notified whenever something changes — a state update, a new comment, a priority shift, an assignee change.

You don't always have to subscribe manually. Plane adds you automatically in a few situations: when you're assigned to something, when someone @-mentions you, or when an admin has set you up as a project-level subscriber. Everything else is opt-in.

Expand All @@ -21,18 +21,6 @@ Open the work item and click **Unsubscribe**. That's it — you'll stop receivin

If you were auto-subscribed (because you were assigned, for example), unsubscribing works the same way. Being removed as an assignee doesn't automatically unsubscribe you — you have to do that yourself if you want to stop getting notifications.

## Subscribe to an epic <Badge type="info" text="Pro" />

Epics have their own subscribe flow, separate from work items.

Open an epic and click the **Subscribe** button in the detail panel. You'll get notified when the epic itself changes — field updates, state changes, comments, and when an epic update (a progress or status post) is published.

Epics work the same way as work items for most notifications. The one thing that's different is **epic updates**. When someone publishes a progress or status update on an epic, Plane sends an email specifically to all epic subscribers. This is separate from the usual change notifications — it's more like a broadcast, letting stakeholders know about deliberate progress posts rather than individual field edits.

If you're subscribed to an epic, you get both: notifications for changes to the epic itself, and emails when an epic update is published.

To unsubscribe, click **Unsubscribe** from the same panel.

## Subscribe to multiple work items at once <Badge type="info" text="Pro" />

If you need to subscribe to several work items in one go:
Expand Down
2 changes: 1 addition & 1 deletion docs/core-concepts/analytics.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ The Projects analytics tab gives you a clear snapshot of how all your projects a

The _Projects by status_ chart breaks things down by where each project sits in its lifecycle. You can see how many projects are still in draft phase versus those that are actively in execution. It's a handy way to understand your project pipeline and see if you've got a good balance between planning and doing.

Below that, you'll find a detailed table that shows you the nitty-gritty details - how many team members are involved, the number of epics and work items, which cycles and modules are part of the project, and even how many pages and views have been created. There's also an intake column that tracks incoming requests or ideas for each project.
Below that, you'll find a detailed table that shows you the nitty-gritty details - how many team members are involved, the number of work items, which cycles and modules are part of the project, and even how many pages and views have been created. There's also an intake column that tracks incoming requests or ideas for each project.

What's really useful here is that you can search through all your projects if you're looking for something specific, and of course, export everything to CSV if you want to do some deeper analysis or create reports for stakeholders.

Expand Down
2 changes: 0 additions & 2 deletions docs/core-concepts/issues/display-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ Grouping helps you organize work items based on shared attributes, making it eas
- Assignees
- Created By
- Milestones
- Epics
- Releases
- Work Item Types
- None
Expand All @@ -59,7 +58,6 @@ You can further refine your view by adding a sub-grouping. For example, you coul
- Assignees
- Created By
- Milestones
- Epics
- Releases
- Work Item Types
- None
Expand Down
172 changes: 19 additions & 153 deletions docs/core-concepts/issues/epics.md
Original file line number Diff line number Diff line change
@@ -1,171 +1,37 @@
---
title: Organize related work items with Epics
description: Create and manage Epics in Plane to organize related work items, track progress across multiple tasks, and align your team around larger objectives.
title: Epics
description: Epics are now a work item type in Plane. Learn what changed, what stayed the same, and where to go next.
---

# Epics <Badge type="info" text="Pro" />

Epics help you group related tasks into a larger work item, providing a hierarchical structure for managing complex projects. This feature is ideal for breaking down major objectives into smaller, manageable pieces while keeping everything organized within a project.
Epics in Plane have moved. They're now a [**work item type**](/work-items/project-work-item-types), living in the same Work Items list as other types your team tracks. If you've been using Epics, this page explains what changed, what stayed the same, and where everything is now.

Use Epics when you need to:
## What changed

- Organize tasks related to a larger objective or feature.
- Track progress and dependencies across multiple related work items.
- Improve visibility into how individual tasks contribute to broader goals.
Previously, Epics had their own dedicated tab in the project sidebar. You managed them separately from work items, and they had their own filtered view, their own settings toggle, and their own sidebar entry.

::: tip
Use an Epic for larger bodies of work that span multiple cycles and extend across different modules.
:::
That separate layer is gone.

## Turn on Epics
Epic is now a **work item type** and is treated exactly like any other type. You filter, group, sort, and manage Epics the same way you work with any other work item. The creation form, the detail view, the bulk editor, the filters, all of it is shared.

![Enable Epics](https://media.docs.plane.so/epics/enable-epics.webp#hero)
What this means in practice:

To start using Epics, turn on the feature for your project:
- **The Epics tab in the sidebar is removed.** Epics live in **Work Items**, filterable by type.
- **The Epics toggle in Project Settings is gone.** Epic is now managed under **Work item Types** settings. If Work Item Types are enabled for your project, Epic is there.
- **Epic is created automatically.** When you enable Work Item Types for a project, Plane creates two types: the default **Task** type and an **Epic** type. You don't set them up manually.
- **Work Item Updates - On Track, At Risk, Off Track - are no longer exclusive to epics.** They're now available on every work item of every type.

1. Go to the [Project settings](/core-concepts/projects/overview#configure-project-settings) for the desired project.
2. Navigate to the **Epics** section on the right pane.
3. Click the **Enable** button.
The levels aren't arbitrary. Task is created at level 0 and Epic at level 1 - this is the default hierarchy structure built into the product. If your workspace has the Hierarchy feature enabled, that structure is enforced automatically: Epics sit above Tasks, Tasks can be sub-items of Epics, and Tasks cannot contain Epics. You don't configure this; it's there by default the moment Work Item Types are enabled.

Once turned on, the Epics tab will appear in the project's sidebar, giving you quick access to create and manage Epics.
## What stayed the same

## Add custom properties to Epics
The data is fully intact. Every comment, every activity log entry, every update, every sub-work item relationship, and every initiative link on your existing epics carried over. Nothing was lost.

Custom properties allow you to add specialized fields to your Epics, helping you track additional information specific to your project's needs. These properties can be configured to capture various types of data.
The way Epics work conceptually hasn't changed either. An epic is still the parent layer above individual work items. Work items still link to an epic through the **Parent** field. Updates from epics still feed into initiative streams as for all work items.

![Add custom properties](https://media.docs.plane.so/epics/add-custom-properties.webp#hero)
## Where to find your epics now

To add custom properties to an Epic:
Open **Work Items** in your project. Click **Filters**, add a **Type** filter, and select **Epic**. Your epics are there, exactly as you left them.

1. Click the **Add new property** button on the Epics pane.
2. In the **Custom Properties** section, fill in the following fields:
- **Title**: Enter a name for your property
- **Description**: Add details about what this property represents
- **Property type**: Select from the available options:
- **Text**: For free-form text input
- **Number**: For numerical values
- **Dropdown**: For predefined selection options
- **Boolean**: For yes/no or true/false values
- **Date**: For temporal information
- **Member picker**: For assigning team members

## Create Epics

![Create Epics](https://media.docs.plane.so/epics/create-epics.webp#hero)

Follow these steps to create a new Epic:

1. Navigate to the **Epics** section under your project.
2. Click the **New Epic** button at the top right of the screen.
3. Provide the following details:
- **Title**: Name your Epic.
- **Description**: Add context for the Epic’s purpose.
- **Properties**: Assign metadata like priority, assignees, labels, and due dates.
4. Click **Save** to create the Epic.

## View and manage Epics

Once created, all Epics can be accessed from the **Epics** section under your project. The Epics screen provides a high-level view of all Epics within a project.

![Epics screen](https://media.docs.plane.so/epics/epics-screen.webp#hero)

::: tip Sort and filter Epics
To help you manage Epics effectively, Plane offers flexible sorting and filtering options.
:::

Clicking on an Epic opens a detailed view where you can quickly view and manage an Epic without leaving your current context.

## Add work items to Epic

![Add work items to Epic](https://media.docs.plane.so/epics/add-issues.webp#hero)

You can add existing work items to the Epic or create new ones directly from the Epic.

::: warning important
A work item can belong to only one Epic. This ensures clarity in organization and avoids overlapping tasks across multiple Epics.
:::

## Duplicate Epics <Badge type="info" text="Pro" />

When you need to create similar Epics or replicate an Epic's structure across projects, Plane allows you to duplicate existing Epics either within the same project or to different projects in your workspace.

To duplicate an Epic, click the ••• menu in the Epic header and select Make a copy. You'll see two options:

### Copy in same project

Creates an identical Epic within the current project with all the same properties, description, and custom field values. The new Epic gets a fresh identifier and maintains the same title, description state, priority, start and due dates.

### Copy in different project

Duplicates the Epic to another project in your workspace that has Epics enabled. This is particularly useful when you have similar large-scale objectives across multiple projects or want to replicate Epics between projects. The copied Epic adapts to the destination project's identifier format and default state.

## Work items list and relations

![Work items and Relations](https://media.docs.plane.so/epics/issues-and-relations.webp#hero)

- See the full list of work items grouped under the Epic.
- Add or remove work items from the Epic.
- Manage work items directly by updating their status, assignee, or priority.

## Epic progress

![Epic progress](https://media.docs.plane.so/epics/epic-progress.webp#hero)

You can track Epic progress visually with a color-coded progress bar that shows:

- Task completion status (e.g., Backlog, Started, Completed).
- Work item counts and completion percentage for each status category.

## Epic updates

Share epic status using updates. This helps keep your team informed and create a timeline of epic progress.

1. Select the tab with rocket icon in the side panel.
2. Click the **Add Update** button.
3. Select the status. Each update can be marked as:
- 🚀 **On Track** - Epic is progressing as planned
- ⚠️ **At Risk** - There are potential work items that need attention
- ❗ **Off Track** - Epic has significant blockers or delays
4. Add your update message.
5. Click **Add update**.

![Add epic updates](https://media.docs.plane.so/epics/add-epic-updates.webp#hero-tr)

### Collaborate on updates

- Start threaded discussions around specific updates or tasks.
- Use emoji reactions for quick feedback.

## Properties, comments, and activity

- View and update the Epic’s key properties like assignee, priority, timelines, and other custom properties.

![Epic properties](https://media.docs.plane.so/epics/epic-properties.webp#hero-tr)

- Add comments to collaborate with your team and to discuss progress, blockers, or updates.

![Epic comments](https://media.docs.plane.so/epics/epic-comments.webp#hero-tr)

- Access the activity log for a history of changes made to the Epic, ensuring transparency and accountability.

![Epic activity](https://media.docs.plane.so/epics/epic-activity.webp#hero-tr)

## Link Work items to Epics

For each work item, you can assign or change a work item's Epic directly in the **Parent** property.

![Link Work items to Epics](https://media.docs.plane.so/epics/link-issue-epic.webp#hero)

## Convert Epics to Work Items <Badge type="tip" text="Business" />

Sometimes you realize that what you thought was a big, complex epic is actually something smaller and more focused. That's where converting an epic to a work item comes in handy. This feature lets you transform an epic into a regular work item, making it easier to track and manage as a single deliverable rather than a collection of tasks.

![convert epic to work item](https://media.docs.plane.so/issues/convert-epic-to-work-item.webp#hero-tr)

From any epic, look for the conversion option in the interface. Click **Convert to work item** and the system will transform your epic while preserving all the important details like title, description, and basic properties.

You can also [convert Work items to Epics](/core-concepts/issues/overview#convert-work-items-to-epics).

---

Epics provide a simple yet powerful way to manage larger goals while keeping your projects organized and your team aligned.
You can also group your Work Items view by **Type** to see epics and other types side by side.
24 changes: 19 additions & 5 deletions docs/core-concepts/issues/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,15 +193,29 @@ Connect relevant project pages and wiki documentation to your work items to prov

Linked pages appear directly in the work item, making it easy for team members to access relevant documentation without leaving the context of their current task.

## Convert work items to epics <Badge type="tip" text="Business" />
## Work item updates

Sometimes a work item grows in scope and complexity, and you realize it's actually big enough to be its own epic with multiple sub-tasks. This feature promotes a regular work item into an epic, giving you the structure and flexibility to break it down into smaller, manageable pieces.
Updates let you post a status snapshot on any work item. Each update carries a status indicator — On Track, At Risk, or Off Track — alongside a message.

![convert work item to epic](https://media.docs.plane.so/issues/convert-work-item-to-epic.webp#hero)
**Post an update:**

From any work item, find the **Convert to Epic** option. The system will ask you to confirm since this action detaches any associated cycles, modules, and parent items. Once converted, you'll have a new epic that you can start breaking down into sub-work items and organizing however makes sense for your project.
1. Open the work item.
2. Click the **Updates** tab in the side panel.
3. Click **Add Update**.
4. Select a status:
- **On Track** — progressing as planned
- **At Risk** — potential blockers that need attention
- **Off Track** — significant blockers or delays
5. Add your message.
6. Click **Add update**.

You can also [convert Epics to Work Items](/core-concepts/issues/epics#convert-epics-to-work-items).
Updates roll up to any initiative the work item is linked to.

## Change a work item's type

To change a work item to an Epic or any other type - use **Switch work item type**. Open the work item, hover next to the work item ID, and click **Switch work item type**. Select the new type from the dropdown and click **Update**.

See [Work Item Types](/work-items/project-work-item-types#switch-work-item-types) for full details.

## Activity and collaboration

Expand Down
Loading
Loading