YouTrack Server
 
2023.3
You are viewing the documentation for an earlier version of YouTrack Server.
  1. Agile Boards
  2. Work with a Backlog

Work with a Backlog

Last modified: 22 March 2024

A backlog is a set of issues that await planning and implementation. In other words, it is the collection of unfinished work that your development team can build to improve the product. Teams normally prioritize issues in the backlog to determine which issues are addressed in each release cycle.

In YouTrack, the collection of issues that are displayed in the backlog on an agile board is represented by a saved search. This search query has the possibility of matching any issue in YouTrack. This means whenever an issue is created that matches the criteria for the saved search, it is added to the backlog automatically.

When you configure a backlog for your board, you can either select an existing saved search as the backlog for the board or create a new one. If you choose to create a new saved search, it is assigned the name that you provide in the board settings. The following format is used to generate the search query:

project: <project(s)> has: -{Board <Board Name>} #Unresolved

That is, the default backlog contains all unresolved issues that are not already assigned to the Board in all the project(s) on the board.

If you want to show a different set of issues in the backlog, you can edit the saved search or select another saved search as the backlog for your board.

To learn more about the backlog on an agile board, watch this demo:

Change View Mode

There are two view modes that are available for issues in the backlog.

Backlog view modes

View Mode

Description

Tree view

Displays issues in a hierarchical list. Issues that are subtasks of parent tasks are nested in a tree structure.

If an issue that matches the saved search is a subtask of an issue that does not match the search criteria, the parent task is shown with a gray background.

List view

Displays issues as a flat list. Only issues that match the saved search are shown. This makes it possible to prioritize issues from different levels in the hierarchical list.

The ability to switch between view modes is restricted to members of the group that has permission to edit the board settings.

The view that works best for you varies from board to board and team to team.

  • For boards that use features or user stories to identify swimlanes with tasks for cards, the Tree view lets you view and manage issues in the backlog in a manner that preserves this hierarchy. Teams can use a saved search that returns a list of features and add issues as subtasks directly in the backlog.

  • For boards that have attribute-based swimlanes or use no swimlanes at all, the List view lets you view and manage only issues that match the saved search.

Prioritize the Backlog

You can reorder your backlog directly on the board to reflect your current prioritization. You can also add subtasks to parent issues directly in the backlog.

The ability to reorder issues in the backlog is limited to members of the group that has permission to update the saved search that is used for issues in the backlog. This option is stored in the settings for the saved search.

To manually prioritize the backlog on the board:

  1. Click the Icon tray button to view the backlog.

  2. Move the pointer over the reorder icon in the upper-left corner of the issue.

  3. Hold down the mouse button and drag the issue to a new location in the list.

    Prioritize backlog

    • Drop the issue vertically to change its position in the list.

    • Drop the issue horizontally to change its level in the parent/subtask hierarchy.

  4. Repeat steps 2 and 3 for each issue in the backlog that you want to reorder.

You can also prioritize the backlog in the Issues list. From the Issues list, you have more view options that let you see a greater level of detail. With the saved search set as the context, issues that are reordered manually are reordered in the backlog as well.

The ability to reorder issues in the Issues list is limited to members of the group that has permission to update the saved search. This option is stored in the settings for the saved search.

To manually prioritize the backlog in the Issues list:

  1. Click the Icon tray button to view the backlog.

  2. Click the Show on issue list link.

    • The list of issues that match the saved search that is used for the backlog is displayed in the Issues list.

    • The saved search is set as the search context.

    warning

    If you don't set the saved search as the search context, the changes made in the Issues list are not reflected in the backlog.

  3. If needed, set the level of detail to Tree view to show the issues in a hierarchical list.

  4. Move the pointer over the reorder icon on the left-most edge of the issue.

  5. Hold down the mouse button and drag the issue to a new location in the list.

When done, the issues in the backlog appear in the specified order when viewed in the Backlog on the agile board.

Issues manually reordered in a save search take priority over the sort order in the search query settings. For example, if two issues from a saved search were manually reordered, changing the sort order in the search query wouldn't change the position of the manually reordered issues.

All issues reordered manually in the backlog to a saved search can be undone from the Issues list.

To discard the custom order of manually prioritized issues:

  1. Click the Icon tray button to view the backlog.

  2. Click the View all Backlog issues in the Issues list icon located next to the saved search.

    • The list of issues that match the saved search that is used for the backlog is displayed in the Issues list.

    • The saved search is set as the search context.

    warning

    If you don't set the saved search as the search context, the changes made in the Issues list are not reflected in the backlog.

  3. Click the Discard custom order link.

    Discard custom order

  4. Click Confirm to discard the custom order from the saved search.

Add Issues to the Backlog

Issues that match the saved search are added to the backlog automatically. This means that you don't necessarily need to open agile board and view the backlog to populate it with issues.

However, if you're reviewing issues in the backlog as a team for planning, grooming, or refinement, you can easily add issues to the backlog without leaving the agile board.

The method that you use to add an issue to the backlog depends on the current view mode:

  • In List view, click the New issue button in the page footer.

    Add backlog issue list view

  • In Tree view, you have the option to add an issue as a subtask to any issue that is visible in the backlog. When you click the Create subtask icon and define the issue, the issue is added as a subtask to the selected issue.

    Add backlog issue tree view

    To add an issue to the top-most level of the hierarchy, use the New issue button in the footer.

If you need to modify the saved search that you use for the backlog, you can edit the saved search in the Issues list, or you can modify the search query directly in the backlog on the board.

When you update the saved search directly in the backlog, you don't have to fumble through the list of saved searches in the Issues list to find the saved search that is linked to your board.

To modify the search query in the backlog:

tip

Requires permissions: Edit Tag or Saved Search

  1. Open an agile board.

  2. Click the Icon tray button to view the backlog.

  3. Click the Edit link next to the name of the saved search. The link is only available if you have permission to edit selected saved search.

    • The Edit saved search dialog opens.

      Edit backlog saved search

  4. Edit any of the settings that you want to update.

    note

    When editing the query parameters for the saved search, note that you are only able to reference projects that are referenced in the general settings for the board. If you specify a project that isn't managed on the board, an error is encountered.

    Setting

    Description

    Name

    The name of the saved search.

    Query

    The saved search query.

    Can view and use

    All the members of the selected group can view the saved search results. This also determines which users can see the name of the saved search in the backlog and see the link to show issues that match the saved search in the Issues list.

    Can edit

    All members of the selected group are allowed to edit the setting of the saved search. This also determines which users have the option to edit the saved search in the backlog and reorder issues in the list.

    Pin to sidebar

    Add the saved search to the sidebar in the Issues list. From the Issues list, you can select the saved search to display a list of issues that match the saved search. This option is enabled on a per-user basis.

    Subscriptions

    Select which events generate notifications for issues that match the saved search. These settings are applied on a per-user basis for the user who edits the saved search.

  5. Click the Apply changes button.

    • The saved search is updated.

    • The list of issues in the backlog is refreshed immediately.

    • Changes that are applied to the list of issues are immediately available to any user who is currently viewing the backlog.

You can use any saved search available to you as a backlog for your board. This includes saved searches that you have created yourself or that are visible to a group you belong to as a member.

note

When you select an existing saved search as the query for the backlog, make sure that all the projects that are included in the search query are also referenced in the general settings for the board. Otherwise, users may encounter errors when moving issues from the backlog to the board.

The ability to select another saved search is restricted to members of the group that has permission to edit the board settings.

To select another saved search as the backlog:

  1. Click the Icon tray button to view the backlog.

  2. Click the name of the backlog and select any available saved search from the drop-down list.

    Select saved search

    • The list of issues in the backlog is updated to match the new saved search.

    • The new list of issues is immediately available to any user who is currently viewing the backlog.