Tasklists [public beta] (#37103)

Co-authored-by: Omer Bensaadon <omerbensaadon@github.com>
Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Felicity Chapman <felicitymay@github.com>

content/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists.md

@@ -20,7 +20,7 @@ topics:
 {% ifversion projects-v2-tasklists %}
 {% note %}
 
-**Note:** For more information about the new iteration of tasklists, which is currently in a private beta, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/about-tasklists)."
+**Note:** For more information about the new iteration of tasklists, which is currently in beta, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/about-tasklists)."
 
 {% endnote %}
 {% endif %}

content/index.md

@@ -118,6 +118,8 @@ childGroups:
     octicon: ProjectIcon
     children:
       - issues
+      - issues/planning-and-tracking-with-projects
+      - issues/managing-your-tasks-with-tasklists
       - search-github
   - name: Developers
     octicon: CodeSquareIcon

content/issues/guides.md

@@ -12,6 +12,7 @@ versions:
 includeGuides:
   - /issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions
   - /issues/planning-and-tracking-with-projects/creating-projects/creating-a-project
+  - /issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists
   - /issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view
   - /issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects
   - /issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects
@@ -25,4 +26,3 @@ includeGuides:
   - /issues/using-labels-and-milestones-to-track-work/managing-labels
   - /issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests
 ---
-

content/issues/index.md

@@ -9,6 +9,7 @@ featuredLinks:
   startHere:
     - /issues/tracking-your-work-with-issues/creating-an-issue
     - /issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects
+    - /issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists
     - /issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects
     - /communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
     - /issues/tracking-your-work-with-issues/planning-and-tracking-work-for-your-team-or-project
@@ -36,6 +37,7 @@ versions:
 children:
   - /tracking-your-work-with-issues
   - /planning-and-tracking-with-projects
+  - /managing-your-tasks-with-tasklists
   - /organizing-your-work-with-project-boards
   - /using-labels-and-milestones-to-track-work
   - /guides

content/issues/managing-your-tasks-with-tasklists/about-tasklists.md

@@ -0,0 +1,37 @@
+---
+title: 'About tasklists'
+intro: 'You can use tasklists to quickly sketch out projects, divide tasks into subtasks, and track issues and pull requests.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+type: overview
+topics:
+  - Issues
+---
+
+{% note %}
+
+**Notes:**
+
+* Tasklists are currently in private beta and subject to change. If you are interested in trying tasklists, you can join the [waitlist](https://aka.ms/tasklist-roadmap-signup). Tasklists build upon the previous iteration of [task lists](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists).
+* For the best experience, we recommend adding no more than 50 tasks to a tasklist and no more than 5 tasklists per issue. There is a hard limit of 250 tasks per tasklist and 10 tasklists per issue.
+
+{% endnote %}
+
+## About tasklists and issue hierarchy
+
+You can add a tasklist to an issue to quickly break down larger pieces of work into subtasks. You can sketch out a draft of your plans, in either Markdown or in the UI, and optionally convert those draft tasks into real issues or add existing issues and pull requests to your tasklists.
+
+![Two views of the same issue. In one, the body is being edited to include the Markdown for tasklists. In the other, the body includes rendered tasklists.](/assets/images/help/projects-v2/tasklist-hero.png)
+
+When you add issues and pull requests to a tasklist, the tasklist will show metadata associated with the issue or pull request, including any labels applied, the avatars of people assigned, and the open/close state. When you view the issues and pull requests that have been added to a tasklist, {% data variables.product.product_name %} shows which issues are tracking that subtask.
+
+![Screenshot that shows the header of an issue. The "Tracked by" information in the header is highlighted with an orange outline.](/assets/images/help/projects-v2/tasklist-tracked-by-pill.png)
+
+Tasklists add support for hierarchies of issues on {% data variables.product.product_name %} by creating relationships between your issues. You can create parent and child relationships, you can also create multiple levels of hierarchy that accurately represent your project by breaking down tasks into exactly the amount of detail that you and your team require.
+
+![Diagram showing the relationships built between issues using tasklists. The "Video game" issue has two tasklists. One of the tasks in those tasklists, "3D models," is an issue with its own tasklist.](/assets/images/help/projects-v2/tasklist-diagram.png)
+
+You can create a tasklist using Markdown or using the {% data variables.product.product_name %} UI. Regardless of how you created your tasklist, you can edit it using either Markdown or the UI. For more information, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/creating-a-tasklist)" and "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist)."
+
+Tasklists also integrate with your projects. When you click on an issue in your project, the side-panel opens and displays the issue's place in the hierarchy on a breadcrumb menu, allowing you to navigate through the issues included in your tasklists. You can also add the "Tracks" and "Tracked-by fields" to your project views to quickly see the relationships between your issues. For information, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists)."

content/issues/managing-your-tasks-with-tasklists/creating-a-tasklist.md

@@ -0,0 +1,87 @@
+---
+title: 'Creating a tasklist'
+intro: 'You can create a tasklist using the {% data variables.product.product_name %} UI or Markdown.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+type: tutorial
+redirect_from:
+  - /early-access/issues/about-tasklists
+  - /issues/tracking-your-work-with-issues/about-tasklists
+topics:
+  - Issues
+---
+
+{% data reusables.projects.tasklists-release-stage %}
+
+## Creating tasklists in the UI
+
+You can use the **Add tasklist** button to quickly add a tasklist to your issue. The **Add tasklist** button is available when you view or edit an issue.
+
+1. Navigate to the issue you want to contain your new tasklist. You can also create a new issue.
+1. At the bottom of the issue description, click {% octicon "plus" aria-hidden="true" %} **Add tasklist**.
+  
+  ![Screenshot of an issue. The "Add tasklist" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-tasklist-ui.png)
+  
+1. You can then add issues, pull requests, and draft tasks to your new tasklist. For more information, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist)."
+
+## Creating tasklists with Markdown
+
+You can create tasklists using Markdown in the issue description (the opening comment of an issue). You can include links to issues and pull requests or create draft issues. 
+
+You can add a tasklist by copying the Markdown below into your issue description:
+
+````markdown{:copy}
+```[tasklist]
+### My tasks
+- [ ] https://github.com/octo-org/octo-repo/issues/45
+- [ ] Draft task
+```
+````
+
+You can also use the **Add tasklist** button while editing your issue to insert the Markdown for a tasklist:
+
+![Screenshot an issue. The "Add tasklist" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-tasklist-markdown.png)
+
+Once you have started editing your tasklist Markdown, you can add new tasks by preceding each new task with `- [ ] ` and then adding either:
+
+* A draft task. Draft tasks are text that can later be converted into issues.
+* The full link to an issue or pull request or, if the issue or pull request is in the same repository as your tasklist, you can use the #ISSUE-NUMBER shorthand syntax. For example, `https://github.com/octo-org/octo-repo/issues/45` or `#45`.
+* If an issue or pull request is in the same repository 
+
+If you add a draft task, it must meet these requirements:
+
+* Draft tasks can be formatted using Markdown.
+* Draft tasks must not exceed 512 characters in length.
+
+Your tasklist will be rendered by {% data variables.product.product_name %} when you preview your changes and when you save the issue. You can then make changes and add issues and draft tasks using the {% data variables.product.product_name %} UI. If you edit the issue description, you will be able to modify the Markdown directly or copy the Markdown to duplicate the tasklist in other issues.
+
+## Changing the title of a tasklist
+
+When you create a new tasklist, the default title is "Tasks." You can modify the title by clicking {% octicon "pencil" aria-hidden="true" %} **Rename** in the tasklist's context menu or by editing the issue's markdown. 
+
+1. In the top-right of the issue body, select {% octicon "kebab-horizontal" aria-label="Show options" %} and click **Edit**.
+
+   ![Screenshot of the header of an issue comment. In the right corner, a horizontal kebab icon is outlined in dark orange.](/assets/images/help/issues/comment-menu.png)
+1. In the fenced code block that starts with ````[tasklist]`, add a header with your new title, such as `### My new title`.
+
+   ![Screenshot of an issue comment in edit mode. Under the line that says "```tasklist", a line that says "### My new title" is outlined in dark orange.](/assets/images/help/issues/edit-tasklist-title.png)
+
+1. Click **Update comment**.
+
+## Copying a tasklist
+
+When you copy your tasklist using the "Copy Markdown" option, {% data variables.product.product_name %} copies Markdown to your clipboard and includes the issue title so you can paste the tasklist outside of GitHub without losing context. See below for an example of a copied Markdown tasklist:
+
+```
+- [x] [Design new landing page](https://github.com/octocat/octoproject/issues/4)
+- [ ] [Translate content into supported languages](https://github.com/octocat/octoproject/issues/11)
+```
+
+1. In the top-right of your tasklist, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+   ![Screenshot of a tasklist. The tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/projects-v2/tasklist-kebab.png)
+
+1. In the menu, click **Copy markdown**.
+
+Your tasklist will be copied to your clipboard as a 

content/issues/managing-your-tasks-with-tasklists/index.md

@@ -0,0 +1,18 @@
+---
+title: 'Managing your issues with tasklists'
+shortTitle: 'Tasklists'
+intro: 'You can use tasklists to divide your issues into smaller subtasks.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+topics:
+  - Issues
+children:
+  - /about-tasklists
+  - /quickstart-for-tasklists
+  - /creating-a-tasklist
+  - /managing-tasks-in-a-tasklist
+  - /using-projects-and-tasklists
+---
+
+{% data reusables.projects.tasklists-release-stage %}

content/issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist.md

@@ -0,0 +1,69 @@
+---
+title: 'Managing tasks in a tasklist'
+intro: 'You can track issues and pull requests as subtasks in a tasklist. You can also add draft tasks and later convert them into issues.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+type: tutorial
+topics:
+  - Issues
+---
+
+{% data reusables.projects.tasklists-release-stage %}
+
+## Adding tasks to a tasklist
+
+You can add draft tasks, issues, and pull requests to a tasklist. Draft tasks are useful for quickly capturing ideas that you can later convert into issues. Unlike issues and pull requests that are referenced from your repositories, draft tasks exist only in your tasklist.
+
+You can add issues and pull requests from any repository you have access to. People who do not have access to the issues and pull requests you add to your tasklist will just see the issue or pull request URL.
+
+1. At the bottom of your tasklist, click **Add item to Tasks**.
+  
+  ![Screenshot of a tasklist. The "Add item to Tasks" field is highlighted with an orange rectangle.](/assets/images/help/projects-v2/tasklist-omnibar.png)
+  
+1. Add your draft task, issue, or pull request.
+
+   * To add a draft task, just type your task and press <kbd>Enter</kbd>.
+   * To add a recently updated issue, click an issue from the list, or use your arrow keys to select it and then press <kbd>Enter</kbd>.
+   * To search for an issue in the current repository, start typing the title of an issue or the issue's number and click on the result, or use your arrow keys to select it and press <kbd>Enter</kbd>.
+   * To add an issue directly using its URL, paste the URL of an issue and press <kbd>Enter</kbd>.
+
+## Converting draft tasks to issues in a tasklist
+
+You can convert draft tasks into issues. Issues are created in the same repository as the issue containing the tasklist.
+
+1. Place your cursor over the draft task you want to convert and next to the draft task, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+   ![Screenshot of a tasklist. To the right of a draft task, the tracking block item menu is outlined in dark orange.](/assets/images/help/projects-v2/tasklist-draft-context-menu.png)
+
+1. In the menu, click **Convert to issue**.
+
+## Setting labels, assignees, and projects from a tasklist
+ 
+1. Place your cursor over the task you want to make changes to and next to the task, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+  ![Screenshot of a tasklist. To the right of a task, the tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/projects-v2/tasklists-item-context-menu.png) 
+
+1. Using the context menu, make your changes.
+   * To set labels, select **Set labels**, and then select one or more labels from the menu.
+   * To set assignees, select **Set assignees**, and then select one or more people from the menu.
+   * To add the issue or pull request to a project, select **Set project**, and then select a project from the menu.
+
+## Dragging tasks to change position and move between tasklists
+
+You can move tasks within a tasklist and move tasks to other tasklists in the same issue.
+
+1. Hover your cursor to the left of the task you want to move until a {% octicon "grabber" aria-hidden="true" %} drag handle appears.
+1. Click on the {% octicon "grabber" aria-hidden="true" %} drag handle and drag the task to the new destination.
+   * Drag the task to another position in the same tasklist.
+   * Drag the task to another tasklist in the same issue.
+
+## Removing tasks from a tasklist
+
+You can remove issues, pull requests, and draft tasks from your tasklist. Issues and pull requests removed from a tasklist are not removed from the repository. Draft tasks are permanently deleted.
+
+1. Place your cursor over the task you want to remove and next to the task, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+   ![Screenshot of a tasklist. To the right of a task, the tracking block item menu is outlined in dark orange.](/assets/images/help/projects-v2/tasklists-item-context-menu.png)
+
+1. In the menu, click **Remove**.

content/issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists.md

@@ -0,0 +1,166 @@
+---
+title: 'Quickstart for tasklists'
+shortTitle: 'Quickstart for tasklists'
+intro: 'Follow this guide to learn how to create and modify tasklists in the UI and with Markdown.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+type: quick_start
+topics:
+  - Issues
+---
+
+## Introduction
+
+This guide demonstrates how to use tasklists to split up a larger piece of work into multiple tasklists and multiple subtasks. You will learn how to create a tasklist using the UI, how to create a tasklist using Markdown, how to make changes to a tasklist, and how to integrate your new tasklists with a project.
+
+To help demonstrate how tasklists can be used to divide work into smaller subtasks, this guide will follow a scenario where we need to create a landing page for a new feature. Feel free to follow this guide but incorporate your own scenario.
+
+## Prerequisites
+
+As you follow this guide, you will create several issues in a repository. You will need a repository that you are able to create issues in.
+
+## Creating an issue to track the work of adding a new landing page
+
+In this step, we will create the parent issue to track the subtasks required to publish the new landing page. 
+
+1. Navigate to the repository where you want to track the work.
+1. Create a new blank issue with the title "Tracking issue for landing page." For more information, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue)."
+
+## Creating the first tasklist
+
+Tasklists are added to the opening comment of an issue (the issue description). Issues can contain multiple tasklists with different titles. This is a great way to categorize your subtasks.
+
+1. Go to the issue you just created. If you have not already done so, press **Submit new issue**.
+1. At the bottom of the issue description, click {% octicon "plus" aria-hidden="true" %} **Add tasklist**.
+  
+  ![Screenshot an issue. The "Add tasklist" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-tasklist-ui.png)
+  
+This will insert an empty tasklist into your issue.
+
+## Adding draft tasks
+
+Draft tasks are text items that are added to your tasklist. Draft tasks appear in your tasklist with a checkbox. You can use draft tasks to quickly sketch out the requirements and subtasks for your project and, optionally, later convert them into issues.
+
+1. If the text field is not already focused, click **Add item to Tasks**.
+  
+  ![Screenshot of a tasklist. The "Add item to Tasks" field is highlighted with an orange rectangle.](/assets/images/help/projects-v2/tasklist-omnibar.png)
+  
+1. Add some draft tasks to sketch out this work. Type your draft task and then press <kbd>Enter</kbd> after each one.
+
+  For our example landing page scenario, you can add:
+    * "Design new landing page"
+    * "Create content for landing page"
+    * "Translate content into supported languages"
+    
+## Converting a draft task into an issue
+
+You can convert your draft tasks into issues. You can convert draft tasks when you're ready to start work on a particular task. The issues are created in the same repository you have used for your tracking issue.
+
+1. Next to the "Design new landing page" draft task, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+  
+  ![Screenshot of a tasklist. To the right of a draft task, the tracking block item menu is outlined in orange.](/assets/images/help/projects-v2/tasklist-draft-context-menu.png)
+  
+1. In the menu, click **Convert to issue**.
+
+## Assigning yourself to the new issue
+
+You can now assign yourself to the new issue without leaving your tasklist.
+
+1. Next to the "Design new landing page" issue in your tasklist, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+  ![Screenshot of a tasklist. To the right of a task, the tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/projects-v2/tasklists-item-context-menu.png) 
+  
+1. In the context menu, click **Set assignees**.
+1. In the list of people, select yourself.
+
+You can also use this context menu to set labels and add an issue to a project.
+
+## Renaming a tasklist
+
+You can change the title of a tasklist to better represent the tasks it is tracking. This is particularly useful when you have multiple tasklists in the same issue and want to segment your tasks.
+
+1. In the top-right of your tasklist, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
+
+   ![Screenshot of a tasklist. The tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/projects-v2/tasklist-kebab.png)
+
+1. In the menu, click **Rename**.
+1. Type a new title for your tasklist and press <kbd>Enter</kbd>.
+    
+    For our example landing page scenario, you could rename this tasklist to "Landing page content."
+    
+## Creating a second tasklist using Markdown
+
+You can create multiple tasklists in a single issue. Each tasklist has its own tasks and title. You can add tasklists using the **Add tasklist** button or by entering Markdown when you edit the issue.
+
+1. At the top of the issue description (the opening comment), click {% octicon "kebab-horizontal" aria-label="Show options" %}.
+  
+  ![Screenshot of an issue containing a tasklist. The "Show options" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/edit-issue-tasklist.png)
+  
+1. In the menu, click **Edit**.
+1. In the issue description, below your first tasklist, add the Markdown below:
+  
+   ````markdown{:copy}
+   ```[tasklist]
+   ### Tasks
+   - [ ] Draft task
+   ```
+   ````
+1. To change the title of this tasklist, type a new title after `### `. For example, change `### Tasks` to `### Backend changes`.
+
+In the next two sections, we will make further changes to the Markdown before saving the comment.
+
+## Adding draft tasks using Markdown
+
+You can quickly add new draft tasks by just typing them directly into your tasklist using Markdown.
+
+1. Add new draft tasks by create a new line after the last task, typing `- [ ] ` and your new task. For example, `- [ ] Sign-up form`.
+1. Edit an existing draft task by modifying the text after `- [ ]`. For example, change `- [ ] Draft task` to `- [ ] Database schema`.
+
+## Adding existing issues using Markdown
+
+You can also track existing issues by adding them to your tasklist. You can add existing issues using Markdown or in the UI by pasting the issue URL. You can add issues and pull requests from any repository you have access to.
+
+1. Start typing `- [ ] ` on a new line and then paste the full URL of an issue. For example, `- [ ] https://github.com/octo-org/octo-repo/issues/45`
+1. Click **Update comment**.
+  
+  ![Screenshot of an issue being edited. There are two tasklists present and the "Update comment" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/tasklist-markdown-draft-edit.png)
+  
+
+You will see your new second tasklist displayed beneath your first tasklist.
+
+## Tracking progress
+
+Tasklists help you quickly see the status and progress of the tasks you have chosen to track.
+
+1. To the left of one of your draft tasks, select the checkbox to mark that task as done.
+1. Click on the issue that you previously converted from a draft.
+1. In the converted issue, at the bottom of the page, click **Close issue**.
+
+When you return to your tasklist and refresh the page, you can see that the issue you just closed now has an icon indicating that is closed. At the top of the issue, below the title, the progress is indicated as "2 of 6 tasks."
+
+  ![Screenshot of an issue containing two tasklists. One issue is closed and one draft task is marked as completed. The progress information is highlighted with an orange rectangle.](/assets/images/help/projects-v2/tasklist-quickstart-progress.png)
+
+## Integrate with a project
+
+The relationships you build in your tasklists are available in your projects. You can quickly see the progress made in each issue, browse through the subtasks, and setup views that use your tasklists.
+
+1. Navigate to a project that's owned by the same user or organization account that you have used for your tasklist and issues. If you don't have a project available, you can create one. For more information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project)."
+1. Create a new view in your project using the table layout. For more information on views, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views)."
+1. Add one of the issues from your tasklists to your project. For more information on adding items to projects, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project)."
+{% data reusables.projects.open-view-menu %}
+1. In the menu, click **Group by** and then select **Tracked by**. This creates a view where your issues are grouped by the issue that is tracking them.
+
+Issues and pull requests are not automatically added to a project when they are added to a tasklist. When you group a view by the "Tracked by" field, {% data variables.product.product_name %} will prompt you add other issues associated with the tasklist.
+
+1. If there are issues in your tasklists that are not part of your project, you can click **1 item not in this project** below the group.
+  
+  ![Screenshot of a project in the table layout. At the bottom of a group, "1 item not in this project" is highlighted with an orange rectangle.](/assets/images/help/projects-v2/item-not-in-project.png)
+  
+1. In the list of issues, click on the issue you want to add. If you have multiple issues, you can choose to add all of them.
+
+## Conclusion
+
+After following this guide, you have created a tracking issue with two tasklists, made changes to those tasklists in the UI and directly with Markdown, converted a draft task into an issue, and integrated your tasklist data with a project. 
+
+To learn more about managing the items in your tasklist, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist)." For more information on integrating tasklists with your projects, see "[AUTOTITLE](/issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists)."

content/issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists.md

@@ -0,0 +1,57 @@
+---
+title: 'Using projects and tasklists'
+intro: 'When issues in your project are tracked by tasklists or contain tasklists, you can use them to create views and filters. You can also browse any linked issues when you display the details for an issue.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: projects-v2-tasklists
+type: overview
+topics:
+  - Issues
+---
+
+{% data reusables.projects.tasklists-release-stage %}
+
+When you add tasklists to your issues and view those issues in your projects, you can use the relationships that you defined in your tasklists to customize views, filter items, and navigate through your issues and pull requests.
+
+When you add an issue with a tasklist to a project, the issues and pull requests in the tasklist are not automatically added to the project. To use the "tracks" and "tracked-by" fields, you will need to add all the issues and pull requests that comprise your tasklist to the project. Consider using the auto-add workflow to automatically add issues to your project. For more information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically)."
+
+When you group a view by "Tracked by", and some tracked issues and pull requests are not part of the project, {% data variables.product.product_name %} will include a note beneath each group with the option to add those missing issues and pull requests. 
+
+## Using the "tracks" field
+
+The "tracks" field shows the number of the issues and pull requests included each issue's tasklists. For more information about this field, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields)."
+
+## Using the "tracked by" field
+
+The "tracked by" field shows the issues with tasklists currently tracking your project's issues. The "tracked by" field can also be used to group and filter views. You can use the filter below to only show issues that are tracked by issue you have specified:
+
+```
+tracked-by:"<OWNER>/<REPO>#<ISSUE NUMBER>"
+```
+
+For example, `tracked-by:"octocat/game#4"` will show any issues in the project that are tracked by a tasklist in issue #4 in the `octocat/game` repository.
+
+You can also group a table layout by the "tracked-by" field. This view configuration results in a list of the issues found in tasklists, clearly grouped by the issue they're associated with, which is shown in the header for each group.
+
+You can also combine filters and grouping by filtering your project for just the issues you want to use, and then grouping with the "tracked-by" field. The example below shows how to filter a view by multiple issues:
+
+```
+tracked-by:"<OWNER>/<REPO>#<ISSUE NUMBER>","<OWNER>/<REPO>#<ISSUE NUMBER>"
+```
+
+For more information about this field, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields)."
+
+## Navigating issue hierarchy with a breadcrumb menu
+
+When the issues added to your project are either tracked by tasklists or contain tasklists, the project side-panel allows you to quickly move through the associated issues. Clicking on either the issues in the tasklists or the breadcrumb menu will open that issue in the side-panel.
+
+1. In your project, click on an issue that either contains a tasklist or is tracked by a tasklist in another issue.
+1. In the issue that opens in the side-bar, you can navigate through the associated issues.
+   * To navigate down the issue hierarchy, and view the tasks that comprise the current issue, click on issues in the tasklist.  
+    
+     ![Screenshot of the header of an issue comment. In the right corner, a horizontal kebab icon is outlined in dark orange.](/assets/images/help/projects-v2/side-panel-tasklist.png)
+    
+   * To navigate up the issue hierarchy, and view the issues that include the current issue as a task, click on an issue number in the breadcrumb menu.  
+    
+     ![Screenshot of the header of an issue comment. In the right corner, a horizontal kebab icon is outlined in dark orange.](/assets/images/help/projects-v2/breadcrumb-menu.png)
+    

content/issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields.md

@@ -9,7 +9,11 @@ topics:
   - Projects
 ---
 
-{% data reusables.projects.tasklists-release-stage %}
+{% note %}
+
+**Note:** Tasklists and the tracks and tracked by fields for Projects are currently in beta and subject to change.
+
+{% endnote %}
 
 You can enable the Tracks and Tracked by fields on your projects to see the relationships between your issues as you add subtasks in tasklists. For more information about creating issue hierarchies in tasklists, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/about-tasklists)."
 

content/issues/tracking-your-work-with-issues/about-tasklists.md

@@ -1,126 +0,0 @@
----
-title: About tasklists
-intro: You can use tasklists to divide your issues into smaller subtasks.
-versions:
-  feature: projects-v2-tasklists
-redirect_from:
-  - /early-access/issues/about-tasklists
----
-
-{% data reusables.projects.tasklists-release-stage %}
-
-## About tasklists
-
-Tasklists add support for hierarchies of issues on {% data variables.product.product_name %}, helping you to keep track of your issues, divide your issues into smaller subtasks, and create new relationships between your issues.
-
-Tasklists build upon the previous iteration of [beta task lists](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists), retaining the ability to convert items into issues, display the progress of a tasklist, and create a "tracks/tracked by" relationship between issues.
-
-The issues you add to your tasklists will be automatically populated to show their assignees and any labels applied.
-
-![Two views of the same issue. In one, the body is being edited to include the Markdown for tasklists. In the other, the body includes rendered tasklists.](/assets/images/help/issues/tasklist-hero.png)
-
-### About integration with {% data variables.projects.projects_v2 %}
-
- Your project's side-panel displays an issue's place in the hierarchy on a breadcrumb menu, allowing you to navigate through the issues included in your tasklists. You can also add the Tracks and Tracked by fields to your project views to quickly see the relationships between your issues. For information, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields)."
-
-## Creating tasklists with Markdown
-
-{% note %}
-
-**Note:** If {% data variables.product.product_name %} cannot render your tasklist, make sure it is formatted like the example below.
-
-Tasklists do not currently support:
-
-- Duplicate issue or pull request links.
-- Indented tasks (i.e, nested tasklist).
-- Empty tasks (i.e, `- [ ]` on a line by itself).
-- Stray newlines.
-- Draft tasks that exceed 512 characters.
-
-{% endnote %}
-
-You can create a tasklist using Markdown in the issue description (the opening comment of an issue). You can include links to issues and pull requests or create draft issues.
-
-1. Start creating a new issue or edit the issue description of an existing issue.
-1. To begin your tasklist, type <code>```[tasklist]</code> (triple backticks and <code>tasklist</code> inside square brackets) on a new line in the issue description.
-1. Optionally, type `### TITLE` on the next line, replacing `TITLE` with a title for your tasklist.
-1. For each item you want to add to your tasklist, type `- [ ]` on a new line, followed by a space, and either a link to an issue, a link to a pull request, or some text to create a draft issue.
-   - You may provide a full link to an issue or pull request or, if the issue or pull request is in the same repository as your tasklist, you can use the #ISSUE-NUMBER shorthand syntax. For example, `https://github.com/octo-org/octo-repo/issues/45` or `#45`.
-   - Tasks can be formatted with Markdown.
-   - Tasks must not exceed 256 characters in length.
-1. To finish your tasklist, type <code>```</code> on a new line after the last item.
-
-Your finished tasklist should look like this:
-
-````
-```[tasklist]
-### My tasks
-- [ ] https://github.com/octo-org/octo-repo/issues/45
-- [ ] Draft issue title
-```
-````
-
-Your tasklist will be rendered by {% data variables.product.product_name %} when you save the issue. You can then make changes and add issues and draft issues using the {% data variables.product.product_name %} UI. If you edit the issue description, you will be able to modify the Markdown directly or copy the Markdown to duplicate the tasklist in other issues.
-
-You can also click {% octicon "checklist" aria-label="Add tasklist" %} in the formatting toolbar to insert a tasklist when creating a new issue or editing an issue description.
-
-![Screenshot of the new issue form. In the formatting toolbar, a checklist icon is outlined in dark orange.](/assets/images/help/issues/tasklist-formatting-toolbar.png)
-
-## Adding issues to a tasklist
-
-1. At the bottom of your tasklist, click **Add item to Tasks**.
-1. Select the issue to add to your tasklist.
-
-   - To add a recently updated issue from the repository, click the issue in the dropdown, or use your arrow keys to select it and then press <kbd>Enter</kbd>.
-   - To search for an issue in the repository, start typing the title of an issue or the issue's number and click on the result, or use your arrow keys to select it and press <kbd>Enter</kbd>.
-   - To add an issue directly using its URL, paste the URL of an issue and press <kbd>Enter</kbd>.
-
-## Creating draft issues in a tasklist
-
-Draft issues are useful to quickly capture ideas that you can later convert into issues. Unlike issues and pull requests that are referenced from your repositories, draft issues exist only in your tasklist.
-
-1. At the bottom of your tasklist, click **Add item to Tasks**.
-1. In the "Type to add an item or paste in an issue URL" field, type your draft issue title and press <kbd>Enter</kbd>.
-
-## Converting draft issues to issues in a tasklist
-
-You can convert draft issues into issues. Issues are created in the same repository as the tasklist's parent issue.
-
-1. Next to the draft issue you want to convert, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
-
-   ![Screenshot of a tasklist. To the right of a task, the tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/issues/tasklist-item-kebab.png)
-
-1. In the menu, click **Convert to issue**.
-
-## Removing an issue or draft issue from a tasklist
-
-You can remove issues and draft issues from your tasklist. Issues removed from a tasklist are not removed from the repository.
-
-1. Next to the draft issue you want to remove, select {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
-
-   ![Screenshot of a tasklist. To the right of a task, the tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/issues/tasklist-item-kebab.png)
-
-1. In the menu, click **Remove**.
-
-## Changing the title of a tasklist
-
-When you create a new tasklist, the default title is "Tasks." You can modify the title by editing the issue's markdown.
-
-1. In the top-right of the issue body, select {% octicon "kebab-horizontal" aria-label="Show options" %} and click **Edit**.
-
-   ![Screenshot of the header of an issue comment. In the right corner, a horizontal kebab icon is outlined in dark orange.](/assets/images/help/issues/comment-menu.png)
-1. In the fenced code block that starts with ````[tasklist]`, add a header with your new title, such as `## My new title`.
-
-   ![Screenshot of an issue comment in edit mode. Under the line that says "```tasklist", a line that says "## My new title" is outlined in dark orange.](/assets/images/help/issues/edit-tasklist-title.png)
-
-1. Click **Update comment**.
-
-## Copying a tasklist
-
-When you copy your tasklist using the "Copy Markdown" option, {% data variables.product.product_name %} copies Markdown to your clipboard and includes the Issue's name so you can paste the tasklist outside of GitHub without losing context.
-
-1. In the top-right of your tasklist, click {% octicon "kebab-horizontal" aria-label="tracking block item menu" %}.
-
-   ![Screenshot of a tasklist. The tracking block item menu, which is labeled with a horizontal kebab icon, is outlined in dark orange.](/assets/images/help/issues/tasklist-kebab.png)
-
-1. In the menu, click **Copy markdown**.

content/issues/tracking-your-work-with-issues/index.md

@@ -13,7 +13,6 @@ children:
   - /about-issues
   - /quickstart
   - /creating-an-issue
-  - /about-tasklists
   - /about-slash-commands
   - /linking-a-pull-request-to-an-issue
   - /creating-a-branch-for-an-issue

data/reusables/projects/tasklists-release-stage.md

@@ -1,5 +1,7 @@
 {% note %}
 
-**Note:** Tasklists and the tracks and tracked by fields for Projects are currently in private beta and subject to change. If you are interested in trying tasklists and using the new fields, you can join the [waitlist](https://aka.ms/tasklist-roadmap-signup).
+**Note:** Tasklists are currently in private beta and subject to change. If you are interested in trying tasklists, you can join the [waitlist](https://aka.ms/tasklist-roadmap-signup).
 
 {% endnote %}
+
+<!-- n.b. separate note on "About tasklists" -->

data/variables/projects.yml

@@ -21,3 +21,5 @@ project_v2_and_v1: '{% ifversion projects-v2 %}{% data variables.projects.projec
 # Limits
 item_limit: '1,200'
 archived_item_limit: '10,000'
+
+tasklists: 'tasklists (beta)'