Merge branch 'main' into repo-sync

content/issues/trying-out-the-new-projects-experience/about-projects.md

@@ -29,7 +29,7 @@ You can use custom fields to add metadata to your tasks. For example, you can tr
 - a number field to track the complexity of a task
 - a single select field to track whether a task is Low, Medium, or High priority
 - a text field to add a quick note
-- an iteration field to plan work week-by-week
+- an iteration field to plan work week-by-week, including support for breaks
 
 ### Viewing your project from different perspectives
 

content/issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects.md

@@ -75,7 +75,7 @@ Additionally, {% data variables.product.prodname_actions %} and the GraphQL API
 
 Take advantage of the various field types to meet your needs.
 
-Use an iteration field to schedule work or create a timeline. You can group by iteration to see if items are balanced between iterations, or you can filter to focus on a single iteration. Iteration fields also let you view work that you completed in past iterations, which can help with velocity planning and reflecting on your team's accomplishments.
+Use an iteration field to schedule work or create a timeline. You can group by iteration to see if items are balanced between iterations, or you can filter to focus on a single iteration. Iteration fields also let you view work that you completed in past iterations, which can help with velocity planning and reflecting on your team's accomplishments. Iteration fields also support breaks to show when you and your team are taking time away from their iterations. For more information, see "[Managing iterations in projects](/issues/trying-out-the-new-projects-experience/managing-iterations)."
 
 Use a single select field to track information about a task based on a preset list of values. For example, track priority or project phase. Since the values are selected from a preset list, you can easily group or filter to focus on items with a specific value.
 

content/issues/trying-out-the-new-projects-experience/creating-a-project.md

@@ -132,7 +132,7 @@ Custom fields can be text, number, date, single select, or iteration:
 - Number: The value must be a number.
 - Date: The value must be a date.
 - Single select: The value must be selected from a set of specified values.
-- Iteration: The value must be selected from a set of date ranges (iterations). Iterations in the past are automatically marked as "completed", and the iteration covering the current date range is marked as "current".
+- Iteration: The value must be selected from a set of date ranges (iterations). Iterations in the past are automatically marked as "completed", and the iteration covering the current date range is marked as "current". For more information, see "[Managing iterations in projects](/issues/trying-out-the-new-projects-experience/managing-iterations)."
 
 1. {% data reusables.projects.open-command-palette %} Start typing any part of "Create new field". When "Create new field" displays in the command palette, select it.
 2. Alternatively, click {% octicon "plus" aria-label="the plus icon" %} in the rightmost field header. A drop-down menu with the project fields will appear. Click **New field**.
@@ -148,7 +148,9 @@ You can later edit the drop down options for single select and iteration fields.
 {% data reusables.projects.project-settings %}
 1. Under **Fields**, select the field that you want to edit.
 1. For single select fields, you can add, delete, or reorder the options.
-2. For iteration fields, you can add or delete iterations, change iteration names, and change the start date and duration of the iteration.
+1. For iteration fields, you can add or delete iterations, change iteration names, and change the start date and duration of the iteration.
+
+   For more information on modifying iteration fields, see "[Managing iterations in projects](/issues/trying-out-the-new-projects-experience/managing-iterations)."
 
 ## Customizing your views
 

content/issues/trying-out-the-new-projects-experience/customizing-your-project-views.md

@@ -125,12 +125,7 @@ Alternatively, click {% octicon "triangle-down" aria-label="the drop-down icon"
 
 Click {% octicon "filter" aria-label="the filter icon" %} at the top of the table to show the "Filter by keyword or by field" bar. Start typing the field name and value that you want to filter by. As you type, possible values will appear.
 
-- To filter for multiple values, separate the values with a comma. For example `label:"good first issue",bug` will list all issues with a label `good first issue` or `bug`.
-- To filter for the absence of a specific value, place `-` before your filter. For example, `-label:"bug"` will only show items that do not have the label `bug`.
-- To filter for the absence of all values, enter `no:` followed by the field name. For example, `no:assignee` will only show items that do not have an assignee.
-- To filter by state, enter `is:`. For example, `is: issue` or `is:open`.
-- Separate multiple filters with a space. For example, `status:"In progress" -label:"bug" no:assignee` will show only items that have a status of `In progress`, do not have the label `bug`, and do not have an assignee.
-- To filter for the current iteration of an iteration field, use `@current`. For example, `sprint:@current`.
+{% data reusables.projects.projects-filters %}
 
 Alternatively, use the command palette.
 
@@ -141,6 +136,8 @@ Alternatively, use the command palette.
 
 In board layout, you can click on item data to filter for items with that value. For example, click on an assignee to show only items for that assignee. To remove the filter, click the item data again.
 
+For more information, see "[Filtering projects](/issues/trying-out-the-new-projects-experience/filtering-projects)."
+
 ## Creating a project view
 
 Project views allow you to quickly view specific aspects of your project. Each view is displayed on a separate tab in your project. 

content/issues/trying-out-the-new-projects-experience/filtering-projects.md

@@ -0,0 +1,26 @@
+---
+title: Filtering projects (beta)
+intro: 'You can filter your projects to focus on specific information.'
+allowTitleToDifferFromFilename: true
+miniTocMaxHeadingLevel: 2
+versions:
+  fpt: '*'
+  ghec: '*'
+topics:
+  - Projects
+  - Organizations
+---
+
+{% data reusables.projects.projects-beta %}
+
+## About filtering projects
+
+You can customize views using filters for item metadata, such as assignees and the labels applied to issues, and by the fields in your project. You can combine filters and save them as views. For more information, see "[Customizing your project views](/issues/trying-out-the-new-projects-experience/customizing-your-project-views)."
+
+To filter a project, click {% octicon "filter" aria-label="The Filter icon" %} and start typing the fields and values you would like to filter for. As you type, possible values will appear. You can also open the command pallet and type "Filter by" to choose from the available filters.
+
+The same filters are available for insights, allowing you to filter the data used to create your charts. For more information, see "[Using insights with projects](/issues/trying-out-the-new-projects-experience/using-insights-with-projects)."
+
+## Syntax for filtering projects
+
+{% data reusables.projects.projects-filters %}

content/issues/trying-out-the-new-projects-experience/index.md

@@ -12,11 +12,14 @@ children:
   - /about-projects
   - /quickstart
   - /creating-a-project
+  - /managing-iterations
   - /customizing-your-project-views
+  - /filtering-projects
   - /using-the-api-to-manage-projects
   - /automating-projects
   - /managing-the-visibility-of-your-projects
   - /managing-access-to-projects
+  - /using-insights-with-projects
   - /best-practices-for-managing-projects
 ---
 

content/issues/trying-out-the-new-projects-experience/managing-iterations.md

@@ -0,0 +1,65 @@
+---
+title: Managing iterations in projects (beta)
+intro: 'You can create iterations to plan upcoming work and group items.'
+allowTitleToDifferFromFilename: true
+miniTocMaxHeadingLevel: 2
+versions:
+  fpt: '*'
+  ghec: '*'
+topics:
+  - Projects
+  - Organizations
+---
+
+{% data reusables.projects.projects-beta %}
+
+## About iterations
+
+You can create an iteration field to associate items with specific repeating blocks of time. Iterations can be set to any length of time, can include breaks, and can be individually edited to modify name and date range. With projects, you can group by iteration to visualize the balance of upcoming work, use filters to focus on a single iteration, and sort by iteration.
+
+When you first create an iteration field, three iterations are automatically created.  You can add additional iterations and make other changes on your project's settings page.
+
+![Screenshot showing the settings for an iteration field](/assets/images/help/issues/iterations-example.png)
+
+## Creating an iteration field
+
+You can create an iteration field using the command palette or the project's interface.
+
+1. {% data reusables.projects.open-command-palette %} Start typing any part of "Create new field". When "Create new field" displays in the command palette, select it.
+
+   Alternatively, click {% octicon "plus" aria-label="the plus icon" %} in the rightmost field header. A drop-down menu with the project fields will appear. Click **New field**.
+1. In the text box, enter a name for the new iteration field.
+1. Select the dropdown menu below and click **Iteration**.
+1. Optionally, if you want to change the starting date from the current day, select the calendar dropdown next to "Starts on" and click on a new starting date.
+2. To change the duration of each iteration, type a new number, then select the dropdown and click either **days** or **weeks**.
+3. Click **Save & create**.
+  
+## Adding new iterations
+
+{% data reusables.projects.project-settings %}
+1. Click the name of the iteration field you want to adjust.
+1. To add a new iteration of the same duration, click **Add iteration**.
+1. Optionally, to customize the duration of the new iteration and when it will start, click {% octicon "triangle-down" aria-label="The triangle icon" %} next to "Add iteration", select a starting date and duration, and click **Add**.
+1. Click **Save changes**.
+
+## Editing an iteration
+
+You can edit iterations in your project settings. You can also access the settings for an iteration field by clicking {% octicon "triangle-down" aria-label="The triangle icon" %} in the table header for the field and clicking **Edit values**.
+
+{% data reusables.projects.project-settings %}
+1. Click the name of the iteration field you want to adjust.
+1. To change the name of an iteration, click on the name and start typing.
+1. To change the date or duration of an iteration, click on the date to open the calendar. Click on the start day, then click the end day, and then click **Apply**.
+1. Optionally, to delete an iteration, click {% octicon "trash" aria-label="The trash icon" %}.
+1. Click **Save changes**.
+
+## Inserting a break
+
+You can insert breaks into your iterations to communicate when you are taking time away from scheduled work. The duration of a new break defaults to the length of the most recently created iteration.
+
+{% data reusables.projects.project-settings %}
+1. Click the name of the iteration field you want to adjust.
+2. On the dividing line above an iteration and to the right, click **Insert break**.
+   ![Screenshot showing location of "Insert break" button](/assets/images/help/issues/iteration-insert-break.png)
+3. Optionally, to change the duration of the break, click on the date to open the calendar. Click on the start day, then click the end day, and then click **Apply**.
+4. Click **Save changes**.

content/issues/trying-out-the-new-projects-experience/using-insights-with-projects.md

@@ -0,0 +1,29 @@
+---
+title: Using insights with projects (beta)
+intro: 'You can view and customize charts that are built from your project''s data.' 
+allowTitleToDifferFromFilename: true
+miniTocMaxHeadingLevel: 2
+versions:
+  fpt: '*'
+  ghec: '*'
+topics:
+  - Projects
+  - Organizations
+---
+
+{% data reusables.projects.insights-alpha %}
+
+## About insights
+
+You can use insights to view and customize charts that use the items added to your project as their source data. The default "Burn up" chart shows item status over time, allowing you to visualize progress. You can apply filters to the default chart and also customize and save charts that are available to everyone that can view the project.
+
+![Screenshot showing an example of the default burn up chart for the current iteration](/assets/images/help/issues/burnup-example.png)
+
+## Creating a chart
+
+1. Navigate to your project.
+2. In the top-right, click {% octicon "graph" aria-label="the graph icon" %} to access insights. This feature is currently in a private preview and is not yet available to all organizations. If insights is not yet enabled for your organization, the {% octicon "graph" aria-label="the graph icon" %} icon will not be available.
+3. In the menu on the left, click **New chart**.
+4. Optionally, to change the name of the new chart, click {% octicon "triangle-down" aria-label="The triangle icon" %}, type a new name, and press <kbd>Return</kbd>.
+5. Above the chart, type filters to change the data used to build the chart. For more information, see "[Filtering projects](/issues/trying-out-the-new-projects-experience/filtering-projects)."
+6. To the right of the filter text box, click **Save changes**.

data/reusables/projects/insights-alpha.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Insights for projects (beta) is currently in private preview and is not yet available to all organizations. 
+
+{% endnote %}

data/reusables/projects/projects-filters.md

@@ -0,0 +1,9 @@
+- To filter for any match of multiple values (an OR query), separate the values with a comma. For example `label:"good first issue",bug` will list all issues labelled `good first issue` or `bug`.
+- To filter for the absence of a specific value, place `-` before your filter. For example, `-label:"bug"` will only show items that do not have the label `bug`.
+- To filter for the absence of all values, enter `no:` followed by the field name. For example, `no:assignee` will only show items that do not have an assignee.
+- To filter by state, enter `is:`. For example, `is: issue` or `is:open`.
+- Separate multiple filters with a space. For example, `status:"In progress" -label:"bug" no:assignee` will show only items that have a status of `In progress`, do not have the label `bug`, and do not have an assignee.
+- To filter for the previous, current, or next iteration of an iteration field, use `@previous`, `@current`, or `@next`. For example, `sprint:@current`.
+- To filter for items assigned to the viewer, use `@me`. For example, `assignee:@me`. Anyone using this view will see items assigned to themselves.
+- To filter date and number fields, use `>`, `>=`, `<`, `<=`, and `..` range queries. For example: `target:2022-03-01..2022-03-15`. For more information, see "[Understanding the search syntax](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax)."
+-