diff --git a/assets/images/help/issues/issue-add-type.png b/assets/images/help/issues/issue-add-type.png new file mode 100644 index 000000000000..d783676ceb5e Binary files /dev/null and b/assets/images/help/issues/issue-add-type.png differ diff --git a/assets/images/help/issues/issue-edit-description.png b/assets/images/help/issues/issue-edit-description.png new file mode 100644 index 000000000000..e0b7e695d964 Binary files /dev/null and b/assets/images/help/issues/issue-edit-description.png differ diff --git a/assets/images/help/issues/issue-edit-title.png b/assets/images/help/issues/issue-edit-title.png new file mode 100644 index 000000000000..331c93a657a3 Binary files /dev/null and b/assets/images/help/issues/issue-edit-title.png differ diff --git a/assets/images/help/issues/issue-type-dropdown.png b/assets/images/help/issues/issue-type-dropdown.png new file mode 100644 index 000000000000..b21967e76a3e Binary files /dev/null and b/assets/images/help/issues/issue-type-dropdown.png differ diff --git a/assets/images/help/issues/issue-type-edit.png b/assets/images/help/issues/issue-type-edit.png new file mode 100644 index 000000000000..2d661df0896b Binary files /dev/null and b/assets/images/help/issues/issue-type-edit.png differ diff --git a/assets/images/help/issues/sub-issue-drop-down.png b/assets/images/help/issues/sub-issue-drop-down.png new file mode 100644 index 000000000000..fba9e7f9a08a Binary files /dev/null and b/assets/images/help/issues/sub-issue-drop-down.png differ diff --git a/assets/images/help/issues/sub-issue-expand.png b/assets/images/help/issues/sub-issue-expand.png new file mode 100644 index 000000000000..cfaa9e87bd57 Binary files /dev/null and b/assets/images/help/issues/sub-issue-expand.png differ diff --git a/assets/images/help/issues/sub-issue-parent.png b/assets/images/help/issues/sub-issue-parent.png new file mode 100644 index 000000000000..99c287c3809f Binary files /dev/null and b/assets/images/help/issues/sub-issue-parent.png differ diff --git a/content/get-started/accessibility/keyboard-shortcuts.md b/content/get-started/accessibility/keyboard-shortcuts.md index ad9fd26e1b56..686106a07a1b 100644 --- a/content/get-started/accessibility/keyboard-shortcuts.md +++ b/content/get-started/accessibility/keyboard-shortcuts.md @@ -159,6 +159,11 @@ If you view a code file in a repository using the **Code** view and click on any |Shift and click | When creating an issue from a task list, open the new issue form in a new tab by holding Shift and clicking the {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists)." | |Command and click (Mac) or
Ctrl+Shift and click (Windows/Linux) | When creating an issue from a task list, open the new issue form in the new window by holding Command or Ctrl+Shift and clicking the {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists)." | | {% endif %} | +| {% ifversion sub-issues %} | +|Option+Shift+c (Mac) or
Alt+Shift+c (Windows/Linux) | Create a new sub-issue. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues)." | +|Option, Shift+a (Mac) or
Alt+Shift+a (Windows/Linux) | Add an existing issue as sub-issue. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues)." | +|Option+Shift+p (Mac) or
Alt+Shift+p (Windows/Linux) | Edit parent issue. | +| {% endif %} | ## "Files changed" tab in pull requests diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md index 300c9635e19d..edb96e107a9d 100644 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md +++ b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md @@ -208,3 +208,31 @@ You can also use a * as a wildcard. | field:*TEXT | **label:*support** will show items with a label that ends with "support." {% endif %} + +{% ifversion issue-types %} + +## Filtering by issue type + +If your organization uses issue types, you can filter for particular types. + +{% data reusables.issues.release-stage %} + +| Qualifier | Example +| ---------- | ------------- +| type:"ISSUE TYPE" | **type:"bug"** will show issues with the "bug" type. + +{% endif %} + +{% ifversion sub-issues %} + +## Filtering by parent issue + +You can filter your sub-issues by their parent issue. + +{% data reusables.issues.release-stage %} + +| Qualifier | Example +| ---------- | ------------- +| parent-issue:OWNER/REPO#ISSUE NUMBER | **parent-issue:octocat/game#4** will show issues with issue #4 in octocat/game as their parent issue. + +{% endif %} diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md new file mode 100644 index 000000000000..a5fc0b7eb1db --- /dev/null +++ b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md @@ -0,0 +1,42 @@ +--- +title: About parent issue and sub-issue progress fields +shortTitle: About sub-issue fields +intro: 'You can show an issue''s parent issue and view sub-issue progress in your projects.' +versions: + feature: sub-issues +type: tutorial +topics: + - Projects +--- + +If your organization uses sub-issues, you can enable the "Parent issue" and "Sub-issue progress" fields on your projects to see the relationships between your issues and the progress made on those issues. + +The "Parent issue" field can be used to group items, allowing you to create views that break down your work using the sub-issue hierarchies you have created. For more about grouping views, see "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#grouping-by-field-values-in-table-layout)." + +You can also filter by the "Parent issue" field to only display items that are sub-issues of a particular issue. You can start by typing "parent-issue" and then selecting an issue from the list. Or, if you know the repository and issue number, you can type the filter in full: + +```text +parent-issue:"/#" +``` + +To use the filter, replace `` with the repository owner, `` with the repository name, and `` with the issue number. See "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects)." + +## Enabling the Parent issue field + +You can enable the "Parent issue" field to see which parent issues the issues in your project belong to. + +1. In table view, in the rightmost field header, click {% octicon "plus" aria-label="the plus icon" %}. + + ![Screenshot of a project. The "Add field" button, indicated by a plus icon, is highlighted with an orange outline.](/assets/images/help/projects-v2/new-field-button.png) + +1. Under "Hidden fields", click **Parent issue**. + +## Enabling the Sub-issue progress + +You can enable the "Sub-issue progress" field to see how many sub-issues have been completed. + +1. In table view, in the rightmost field header, click {% octicon "plus" aria-label="the plus icon" %}. + + ![Screenshot of a project. The "Add field" button, indicated by a plus icon, is highlighted with an orange outline.](/assets/images/help/projects-v2/new-field-button.png) + +1. Under "Hidden fields", click **Sub-issue progress**. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md index 314423b12832..d2da9f2f4e79 100644 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md +++ b/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md @@ -12,6 +12,7 @@ children: - /about-date-fields - /about-single-select-fields - /about-iteration-fields + - /about-parent-issue-and-sub-issue-progress-fields - /renaming-custom-fields - /deleting-custom-fields allowTitleToDifferFromFilename: true diff --git a/content/issues/tracking-your-work-with-issues/about-issues.md b/content/issues/tracking-your-work-with-issues/about-issues.md index 8e22db09c2f3..2737db321d96 100644 --- a/content/issues/tracking-your-work-with-issues/about-issues.md +++ b/content/issues/tracking-your-work-with-issues/about-issues.md @@ -1,6 +1,6 @@ --- title: About issues -intro: 'Use {% data variables.product.prodname_github_issues %} to track ideas, feedback, tasks, or bugs for work on {% data variables.product.company_short %}.' +intro: 'Learn how you can use {% data variables.product.prodname_github_issues %} to track ideas, feedback, tasks, or bugs.' redirect_from: - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/about-issues - /articles/creating-issues @@ -16,46 +16,47 @@ topics: - Issues - Project management --- -## About issues -{% data variables.product.prodname_github_issues %} are items you can create in a repository to plan, discuss and track work. +You can create issues in your repository to plan, discuss, and track work. Issues are quick to create, flexible, and can be used in many ways. Issues can track bug reports, new features and ideas, and anything else you need to write down or discuss with your team. {% ifversion sub-issues %}You can also break your work down further by adding sub-issues and easily browse the full hierarchy of work to be done.{% endif %} -Issues are simple to create and flexible to suit a variety of scenarios. You can use issues to track work, give or receive feedback, collaborate on ideas or tasks, and efficiently communicate with others. +Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository,{% ifversion sub-issues %} while adding sub-issues,{% endif %} convert a comment in an issue or pull request, create an issue from a specific line of code, or via a URL query. You can also create an issue from your platform of choice: through the web UI, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_cli %}, GraphQL and REST APIs, or {% data variables.product.prodname_mobile %}. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue)." -### Integrated with {% data variables.product.company_short %} +{% ifversion sub-issues %} -Issues let you track your work on {% data variables.product.company_short %}. When you mention an issue in another issue or pull request, the issue's timeline reflects the cross-reference so that you can keep track of related work. To indicate that work is in progress, you can link an issue to a pull request. When the pull request merges, the linked issue automatically closes. +## About sub-issues -For more information on keywords, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)." +{% data reusables.issues.release-stage %} -### Quickly create issues +{% data reusables.issues.about-sub-issues %} See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues)" and "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues)." -Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository,{% ifversion fpt or ghec %} an item in a task list,{% endif %} a note in a project, a comment in an issue or pull request, a specific line of code, or a URL query. You can also create an issue from your platform of choice: through the web UI, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_cli %}, GraphQL and REST APIs, or {% data variables.product.prodname_mobile %}. For more information, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue)." +{% endif %} -### Track work +## About integration with {% data variables.product.github %} -You can organize and prioritize issues with projects. {% ifversion fpt or ghec %}To track issues as part of a larger issue, you can use task lists.{% endif %} To categorize related issues, you can use labels and milestones. +Issues integrate with your work all across {% data variables.product.github %}. Mentioning an issue in another issue or pull request will create references between them and using keywords, like `fixes:`, in your pull requests will automatically close the associated issues. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue)." -For more information about projects, see {% ifversion projects-v2 %}"[AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)." {% else %}"[AUTOTITLE](/issues/organizing-your-work-with-project-boards)."{% endif %} {% ifversion fpt or ghec %}For more information about task lists, see "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists)." {% endif %}For more information about labels and milestones, see "[AUTOTITLE](/issues/using-labels-and-milestones-to-track-work)." +{% data variables.projects.projects_v2_caps %} is strongly integrated with issues. All your issue metadata is available in your projects, allowing you to create views and filters to represent your work. See "[AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)." -### Stay up to date +## Staying up to date To stay updated on the most recent comments in an issue, you can subscribe to an issue to receive notifications about the latest comments. To quickly find links to recently updated issues you're subscribed to, visit your dashboard. For more information, see "[AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications)" and "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard)." -### Community management +You can assign yourself and teammates to issues to make it clear who is working on an issue and also make it easier for you to locate your issues. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users)" and "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests)." + +## Community management -To help contributors open meaningful issues that provide the information that you need, you can use {% ifversion fpt or ghec %}issue forms and {% endif %}issue templates. For more information, see "[AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests)." +To help contributors open meaningful issues that provide the information that you need, you can use {% ifversion fpt or ghec %}issue forms and {% endif %}issue templates. See "[AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests)." -{% ifversion fpt or ghec %}To maintain a healthy community, you can report comments that violate {% data variables.product.prodname_dotcom %}'s [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines). For more information, see "[AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam)."{% endif %} +{% ifversion fpt or ghec %}To maintain a healthy community, you can report comments that violate {% data variables.product.github %}'s [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines). See "[AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam)."{% endif %} -### Efficient communication +## Efficient communication You can @mention collaborators who have access to your repository in an issue to draw their attention to a comment. To link related issues in the same repository, you can type `#` followed by part of the issue title and then clicking the issue that you want to link. To communicate responsibility, you can assign issues. If you find yourself frequently typing the same comment, you can use saved replies. -{% ifversion fpt or ghec %} For more information, see "[AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)" and "[AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users)." +{% ifversion fpt or ghec %} See "[AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)" and "[AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users)." {% endif %} {% ifversion discussions %} -### Comparing issues and discussions +## Comparing issues and discussions Some conversations are more suitable for {% data variables.product.prodname_discussions %}. {% data reusables.discussions.you-can-use-discussions %} For guidance on when to use an issue or a discussion, see "[AUTOTITLE](/get-started/using-github/communicating-on-github)." diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/index.md b/content/issues/tracking-your-work-with-issues/configuring-issues/index.md index 4f52cd6e0d2f..9eb6f25af42a 100644 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/index.md +++ b/content/issues/tracking-your-work-with-issues/configuring-issues/index.md @@ -10,4 +10,5 @@ topics: children: - /quickstart - /planning-and-tracking-work-for-your-team-or-project + - /managing-issue-types-in-an-organization --- diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md b/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md new file mode 100644 index 000000000000..4ac78256c421 --- /dev/null +++ b/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md @@ -0,0 +1,44 @@ +--- +title: Managing issue types in an organization +intro: 'Learn about issue types and how to manage them in your organization.' +versions: + feature: 'issue-types' +type: overview +topics: + - Project management +shortTitle: 'Managing issue types' +permissions: 'Organization owners can modify issue types.' +--- + +{% data reusables.issues.release-stage %} + +You can use issue types to classify and manage different types of issues across your organization. You can create up to ten issue types that your organization members can apply to issues, making it easier for you and your members to find issues and plan work. + +Default issue types are included in every organization, but these can edited, disabled, or deleted. The default types are task, bug, and feature. + +When you add an issue type to an issue, the type will be shown on any lists of issues and in the issues themselves. You can filter and search by issue type and use issue types when creating filters and views in your projects. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#filtering-by-issue-type)" and "[AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects#filtering-by-issue-type)." + +## Adding an issue type + +{% data reusables.issues.access-issue-types-settings %} +1. On the right side of the page, click **Create new type**. +1. Under "Type name", type the name of your new issue type. +1. Under "Description", to help other people understand the purpose of your new issue type, type a description. +1. Under "Color", click on the color you would like for the new issue type. +1. Optionally, to stop the new issue type being available in public repositories, select **Private repositories only**. +1. Click **Create**. + +## Making changes to issue types + +You can change the name, description, color, and public repository visibility of your issue types. + +You can also choose to disable or delete an issue type. If you disable an issue type, it will not be shown and it won't be possible to set an issue to that type, but if you later decide to enable the issue type, it will be displayed again on any issues previously set to the issue type. If you delete an issue type, it is permanently removed. + +{% data reusables.issues.access-issue-types-settings %} +1. To the right of the issue type you want to make changes to, click {% octicon "kebab-horizontal" aria-label="open type options" %}. + + ![Screenshot of the issue types settings page for an organization. The "open type options" button is highlighted with an orange rectangle.](/assets/images/help/issues/issue-type-edit.png) + +1. In the menu, click **Edit** and make your changes. + * To make changes to the type name, description, color, and if the issue type should only appear for private repositories. Then click **Save**. + * To disable or delete the issue type, in the "Danger zone", click **Disable** or **Delete** and follow the prompts. diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md b/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md index 058365d453e4..5e504821894f 100644 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md +++ b/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md @@ -84,6 +84,16 @@ Below we have added a task list to our Project Octocat issue, breaking it down i ![Screenshot of an issue called "Front-end work for Project Octocat." The issue body contains a task list, with a checkbox preceding each issue link.](/assets/images/help/issues/quickstart-add-task-list-to-issue.png) +{% ifversion sub-issues %} + +### Breaking down your work with sub-issues + +{% data reusables.issues.release-stage %} + +{% data reusables.issues.about-sub-issues %} See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues)" and "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues)." + +{% endif %} + ## Making decisions as a team You can use issues and discussions to communicate and make decisions as a team on planned improvements or priorities for your project. Issues are useful when you create them for discussion of specific details, such as bug or performance reports, planning for the next quarter, or design for a new initiative. Discussions are useful for open-ended brainstorming or feedback, outside the codebase and across repositories. For more information, see "[AUTOTITLE](/get-started/using-github/communicating-on-github#which-discussion-tool-should-i-use)." diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md b/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md index 2feb6b53b5bf..8dd18bc88893 100644 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md +++ b/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md @@ -92,6 +92,12 @@ You can use issues for a wide range of purposes. For example: * Planning tasks * Reporting bugs +{% ifversion sub-issues %} + +To break your issue down into more manageable tasks, you can add multiple levels of sub-issues. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues)." + +{% endif %} + Here are some helpful resources for taking your next steps with {% data variables.product.prodname_github_issues %}: * To learn more about issues, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues)." diff --git a/content/issues/tracking-your-work-with-issues/index.md b/content/issues/tracking-your-work-with-issues/index.md index f9cc3077cbcf..9029bc314541 100644 --- a/content/issues/tracking-your-work-with-issues/index.md +++ b/content/issues/tracking-your-work-with-issues/index.md @@ -16,12 +16,4 @@ children: redirect_from: - /issues/tracking-your-work-with-issues/creating-issues - /issues/tracking-your-work-with-issues/managing-issues - - /early-access/issues/about-tasklists - - /issues/tracking-your-work-with-issues/about-tasklists - - /issues/managing-your-tasks-with-tasklists/about-tasklists - - /issues/managing-your-tasks-with-tasklists/creating-a-tasklist - - /issues/managing-your-tasks-with-tasklists - - /issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist - - /issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists - - /issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists --- diff --git a/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md b/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md new file mode 100644 index 000000000000..10a492f7703a --- /dev/null +++ b/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md @@ -0,0 +1,49 @@ +--- +title: Adding sub-issues +intro: 'Learn about using sub-issues to break down your work into tasks.' +versions: + feature: 'sub-issues' +type: overview +topics: + - Project management +permissions: 'People with at least triage permissions for a repository can add sub-issues.' +redirect_from: + - /early-access/issues/about-tasklists + - /issues/tracking-your-work-with-issues/about-tasklists + - /issues/managing-your-tasks-with-tasklists/about-tasklists + - /issues/managing-your-tasks-with-tasklists/creating-a-tasklist + - /issues/managing-your-tasks-with-tasklists + - /issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist + - /issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists + - /issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists +--- + +{% data reusables.issues.release-stage %} + +You can add sub-issues to an issue to break down larger pieces of work into tasks. Your sub-issues show their relationship to the parent issue allowing you to track your work across {% data variables.product.github %}. Parent issues and sub-issue progress is also available in your {% data variables.projects.projects_v2 %}, allowing you to build views, filter, and group by parent issue. + +Your sub-issues can themselves contain sub-issues, allowing you to create full hierarchies of issues that visualize entire projects or pieces of work and show the relationships between your issues. + +You can add up to fifty sub-issues per parent issue and create up to eight levels of nested sub-issues. + +## Creating a sub-issue + +1. Navigate to the issue that you want to add a sub-issue to. +1. At the bottom of the issue description, click **Create sub-issue**. +1. In the dialog, type the title for your sub-issue. +1. Optionally, type the description for your issue, and set {% ifversion issue-types %}the issue type and{% endif %} any assignees, labels, projects, and milestones. +1. Optionally, if you want to continue create sub-issues for this parent issue, select **Create more sub-issues**. +1. Click **Create**. + +## Adding an existing issue as a sub-issue + +1. Navigate to the issue that you want to add a sub-issue to. +1. At the bottom of the issue description, next to "Create sub-issue", click {% octicon "triangle-down" aria-label="View more sub-issue options" %}. + + ![Screenshot of the sub-issues section below the issue description. The "View more sub-issue options" button is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-drop-down.png) + +1. In the drop-down menu, click **Add existing issue**. +1. Select the issue that you want to add as a sub-issue. + * Select an issue from one of the suggestions. + * In the "Search issues" field, type an issue title or issue number, then click on the results. + * To add issues from other repositories, click {% octicon "arrow-left" aria-label="Back to repository selection" %} next to the repository name and select a different repository. diff --git a/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md b/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md new file mode 100644 index 000000000000..0633ec492d09 --- /dev/null +++ b/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md @@ -0,0 +1,32 @@ +--- +title: Browsing sub-issues +intro: 'Learn how to navigate issue hierarchy in your repositories.' +versions: + feature: 'sub-issues' +type: overview +topics: + - Project management +--- + +{% data reusables.issues.release-stage %} + +{% data reusables.issues.about-sub-issues %} + +## Navigating issue hierarchy + +You can browse through all levels of sub-issues from the parent issue. + +1. Navigate to the parent issue. +1. To view the sub-issues under another sub-issue, click the expand toggle ({% octicon "triangle-right" aria-hidden="true" %}). + + ![Screenshot of a sub-issues section. The expand toggle is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-expand.png) + +## Finding a sub-issue's parent issue + +When you view a sub-issue, you can always find a link back to the parent issue in the header below the issue title. + +![Screenshot of a sub-issue's header. The link to the parent issue, "Parent: create a scoreboard", is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-parent.png) + +## Using sub-issues in your projects + +You can add sub-issues to your projects and make use of the hierarchy data for building views, grouping items, and filtering your views. See "[AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields)." diff --git a/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md b/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md new file mode 100644 index 000000000000..43b6fe598c2a --- /dev/null +++ b/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md @@ -0,0 +1,62 @@ +--- +title: Editing an issue +intro: 'Learn how to make changes to an existing issue.' +permissions: 'Issue authors, people with write access or higher in repositories owned by an organization, and collaborators in repositories owned by a personal account can make changes to issues. {% data reusables.enterprise-accounts.emu-permission-repo %}' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +topics: + - Pull requests + - Issues + - Project management +type: how_to +--- + +## Editing an issue title + +You can edit an issue's title. The change to the title is added to the issue's timeline. + +1. Navigate to the issue you want to edit. +1. To the right of the issue title, click **Edit**. + + ![Screenshot of an issue header, the "Edit" button is highlighted with an orange outline.](/assets/images/help/issues/issue-edit-title.png) + +1. Type your new title. +1. Click **Save**. + +## Editing an issue description + +You can also make changes to the issue description. The edit history is available unless the author or a person with write access removes it. See "[AUTOTITLE](/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment)." + +1. Navigate to the issue you want to edit. +1. At the top right of the issue description, click {% octicon "kebab-horizontal" aria-label="Issue body actions" %}. + + ![Screenshot of an issue description. The "Issue body actions" button is highlighted with an orange outline.](/assets/images/help/issues/issue-edit-description.png) + +1. In the menu, click {% octicon "pencil" aria-hidden="true" %} **Edit**. +1. Type your changes to the issue description. +1. Click **Save**. + +{% ifversion issue-types %} + +## Adding or changing the issue type + +{% data reusables.issues.release-stage %} + +You can add an issue type or make changes to an existing issue type. + +1. Navigate to the issue you want to edit. +1. To the right of the issue, in the sidebar, click **Type**. + + ![Screenshot of an issue sidebar. The "Add issue type" button is highlighted with an orange outline.](/assets/images/help/issues/issue-add-type.png) + +1. In the list, select a new issue type. +1. Click **Save**. + +{% endif %} + +## Further reading + +* [AUTOTITLE](/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue) +* [AUTOTITLE](/issues/tracking-your-work-with-issues/administering-issues/deleting-an-issue) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md b/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md index 417541b15887..4d695dd901a3 100644 --- a/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md +++ b/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md @@ -67,6 +67,48 @@ You can filter issues and pull requests to find: ![Screenshot of the list of issues for a repository. Above the list, a dropdown menu, labeled "Filters", is outlined in dark orange.](/assets/images/help/issues/issues-filter-dropdown.png) +{% ifversion issues-advanced-search %} + +{% webui %} + +## Building advanced filters for issues + +{% data reusables.issues.release-stage %} + +You can build advanced filters using boolean and nested queries on your repository's issues page. As you type your filter, {% data variables.product.github %} will show available qualifiers, suggest values, and warn when there is a problem with your filter. + +### Using boolean operators + +You can use `AND` and `OR` operators to refine your filters. + +Use `AND` when you need results where both statements are true. In the example filter below, the results will be comprised of issues with the "Bug fix" label that are assigned to the @octocat user. + +```text +label:"Bug fix" AND assignee:octocat +``` + +To return results where either statement is true, use `OR`. In the example below, the results will contain issues assigned to either @octocat or @hubot. + +```text +assignee:octocat OR assignee:hubot +``` + +If you choose not to use `AND` and `OR` operators, {% data variables.product.github %} will treat a space between statements as an `AND` operator unless you are using an `org`, `repo`, or `user` field to filter by ownership where any spaces will be treated as an `OR` operator. + +### Using parentheses for more complicated filters + +You can also use parentheses to nest filters and group qualifiers. In the example below, the results will contain issues that are either assigned to @octocat with the "bug" issue type or assigned to @hubot with the "Enchancement" issue type. + +```text +(type:"Bug" AND assignee:octocat) OR (type:"Enhancement" AND assignee:hubot) +``` + +You can nest filters using parentheses up to five levels deep. It's not currently possible to include the `repo`, `org`, or `user` qualifiers within parentheses. + +{% endwebui %} + +{% endif %} + ## Filtering issues and pull requests by assignees Once you've [assigned an issue or pull request to someone](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users), you can find items based on who's working on them. @@ -99,6 +141,24 @@ Once you've [applied labels to an issue or pull request](/issues/using-labels-an {% endtip %} +{% ifversion issue-types %} + +## Filtering by issue type + +{% data reusables.issues.release-stage %} + +If your organization uses issue types, you can filter issues for a particular type. You can also type the `type:` qualifier directly into your filter. + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.sidebar-issues %} +1. Above the list of issues, select the **Types** dropdown menu. + + ![Screenshot of a list of issues. In the header above the list, a dropdown menu, labeled "Types", is outlined in dark orange and the Issue Types menu is open.](/assets/images/help/issues/issue-type-dropdown.png) + +1. In the list of type, click an issue type. + +{% endif %} + ## Filtering pull requests by review status You can use filters to list pull requests by review status and to find pull requests that you've reviewed or other people have asked you to review. @@ -122,7 +182,7 @@ You can filter a repository's list of pull requests to find: ## Using search to filter issues and pull requests -You can use advanced filters to search for issues and pull requests that meet specific criteria. +You can use filters to search for issues and pull requests that meet specific criteria. ### Searching for issues and pull requests @@ -182,8 +242,10 @@ For issues, you can also use search to: * Filter for issues that are linked to a pull request by a closing reference: `linked:pr`{% ifversion issue-close-reasons %} * Filter issues by the reason they were closed: `is:closed reason:completed` or `is:closed reason:"not planned"`{% endif %} +{% ifversion issue-types %}* Filter for issues with a particular type: `is:open type:"Bug"`{% endif %} For pull requests, you can also use search to: + * Filter [draft](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) pull requests: `is:draft` * Filter pull requests that haven't been [reviewed](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) yet: `state:open type:pr review:none` * Filter pull requests that [require a review](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) before they can be merged: `state:open type:pr review:required` diff --git a/content/issues/tracking-your-work-with-issues/using-issues/index.md b/content/issues/tracking-your-work-with-issues/using-issues/index.md index 0f4b3fcaf6ec..bfa3a7b76aaf 100644 --- a/content/issues/tracking-your-work-with-issues/using-issues/index.md +++ b/content/issues/tracking-your-work-with-issues/using-issues/index.md @@ -9,8 +9,11 @@ topics: - Issues children: - /creating-an-issue + - /adding-sub-issues - /assigning-issues-and-pull-requests-to-other-github-users + - /editing-an-issue - /viewing-all-of-your-issues-and-pull-requests + - /browsing-sub-issues - /filtering-and-searching-issues-and-pull-requests - /creating-a-branch-for-an-issue - /linking-a-pull-request-to-an-issue diff --git a/content/search-github/searching-on-github/searching-issues-and-pull-requests.md b/content/search-github/searching-on-github/searching-issues-and-pull-requests.md index 981ee9f59219..4293627692a3 100644 --- a/content/search-github/searching-on-github/searching-issues-and-pull-requests.md +++ b/content/search-github/searching-on-github/searching-issues-and-pull-requests.md @@ -20,6 +20,7 @@ You can search for issues and pull requests globally across all of {% data varia **Tips:**{% ifversion ghes %} * This article contains example searches on the {% data variables.product.prodname_dotcom %}.com website, but you can use the same search filters on {% data variables.location.product_location %}.{% endif %} +{% ifversion issues-advanced-search %}* If your organization has opted-in to the {% data variables.release-phases.public_preview %} of advanced issue search, you can use boolean and nested queries on your repository's issues page. See "[AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues)."{% endif %} * For a list of search syntaxes that you can add to any search qualifier to further improve your results, see "[AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax)". * Use quotations around multi-word search terms. For example, if you want to search for issues with the label "In progress," you'd search for `label:"in progress"`. Search is not case sensitive. * Use a minus (hyphen) symbol to exclude results that match a qualifier. For example, to ignore issues created by the "octocat" user, you'd use `-author:octocat` in your search. Note that this does not work for [missing metadata qualifiers](#search-by-missing-metadata). diff --git a/data/features/issue-types.yml b/data/features/issue-types.yml new file mode 100644 index 000000000000..b3bc3b123567 --- /dev/null +++ b/data/features/issue-types.yml @@ -0,0 +1,4 @@ +# Issue 13435 +versions: + fpt: '*' + ghec: '*' diff --git a/data/features/issues-advanced-search.yml b/data/features/issues-advanced-search.yml new file mode 100644 index 000000000000..3700e534d980 --- /dev/null +++ b/data/features/issues-advanced-search.yml @@ -0,0 +1,4 @@ +# Issue 14644 +versions: + fpt: '*' + ghec: '*' diff --git a/data/features/issues-react.yml b/data/features/issues-react.yml new file mode 100644 index 000000000000..fe41bbbd7ea5 --- /dev/null +++ b/data/features/issues-react.yml @@ -0,0 +1,4 @@ +# Issue 10158 (Issues 2.0) +versions: + fpt: '*' + ghec: '*' diff --git a/data/features/sub-issues.yml b/data/features/sub-issues.yml new file mode 100644 index 000000000000..fee36c9a085c --- /dev/null +++ b/data/features/sub-issues.yml @@ -0,0 +1,4 @@ +# Issue 15008 +versions: + fpt: '*' + ghec: '*' diff --git a/data/reusables/issues/about-sub-issues.md b/data/reusables/issues/about-sub-issues.md new file mode 100644 index 000000000000..413a0486938e --- /dev/null +++ b/data/reusables/issues/about-sub-issues.md @@ -0,0 +1 @@ +You can add sub-issues to an issue to quickly break down larger pieces of work into tasks. Sub-issues add support for hierarchies of issues on {% data variables.product.github %} by creating relationships between your issues. You can create multiple levels of sub-issues that accurately represent your project by breaking down tasks into exactly the amount of detail that you and your team require. diff --git a/data/reusables/issues/access-issue-types-settings.md b/data/reusables/issues/access-issue-types-settings.md new file mode 100644 index 000000000000..433269e963bc --- /dev/null +++ b/data/reusables/issues/access-issue-types-settings.md @@ -0,0 +1,3 @@ +{% data reusables.profile.access_org %} +{% data reusables.profile.org_settings %} +1. In the "Code, planning, and automation" section of the sidebar, select **{% octicon "table" aria-hidden="true" %} Planning**, then click **Issue types**. diff --git a/data/reusables/issues/release-stage.md b/data/reusables/issues/release-stage.md new file mode 100644 index 000000000000..b503d75980de --- /dev/null +++ b/data/reusables/issues/release-stage.md @@ -0,0 +1,3 @@ +>[!NOTE] +>Issue types, sub-issues, and advanced issue search are currently in an opt-in {% data variables.release-phases.public_preview %} for organizations. To learn more and add your organization to the waitlist, see the "[GitHub Blog](https://github.blog/changelog/2024-10-01-evolving-github-issues-public-preview)." + diff --git a/data/reusables/projects/create-issue-modal.md b/data/reusables/projects/create-issue-modal.md index 8aa27c381327..dcb4001172fa 100644 --- a/data/reusables/projects/create-issue-modal.md +++ b/data/reusables/projects/create-issue-modal.md @@ -3,17 +3,12 @@ ![Screenshot showing the bottom row of a table view. The "+" button is highlighted with an orange outline.](/assets/images/help/projects-v2/omnibar-add.png) 1. Click **Create new issue**. - 1. At the top of the "Create new issue" dialog, select the repository where you want the new issue to be created. - + ![Screenshot showing the "Create new issue" dialog.](/assets/images/help/projects-v2/issue-create-form.png) - + 1. Below the repository dropdown, type a title for the new issue. - 1. Optionally, use the fields below the title field to set assignees, labels, and milestones, and add the new issue to other projects. - 1. Optionally, type a description for your issue. - 1. Optionally, if you want to create more issues, select **Create more** and the dialog will reopen when you create your issue. - 1. Click **Create**. diff --git a/data/reusables/repositories/assign-an-issue-as-project-maintainer.md b/data/reusables/repositories/assign-an-issue-as-project-maintainer.md index ea40e8c4a2bb..84540e9395aa 100644 --- a/data/reusables/repositories/assign-an-issue-as-project-maintainer.md +++ b/data/reusables/repositories/assign-an-issue-as-project-maintainer.md @@ -1 +1 @@ -1. If you're a project maintainer, you can [assign the issue to someone](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users), [add it to a {% data variables.projects.project_v2 %}](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project#assigning-a-project-from-within-an-issue-or-pull-request), [associate it with a milestone](/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests), or [apply a label](/issues/using-labels-and-milestones-to-track-work/managing-labels). +1. If you're a project maintainer, you can [assign the issue to someone](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users), [add it to a {% data variables.projects.project_v2 %}](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project#assigning-a-project-from-within-an-issue-or-pull-request), [associate it with a milestone](/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests), {% ifversion issue-types %}[set the issue type](/issues/tracking-your-work-with-issues/using-issues/editing-an-issue#adding-or-changing-the-issue-type), {% endif %}or [apply a label](/issues/using-labels-and-milestones-to-track-work/managing-labels).