[2022-11-28]: Discussions Category Forms - [Limited Public Beta] (github#32120)

Co-authored-by: github-actions <[email protected]>
Co-authored-by: Laura Coursen <[email protected]>
Co-authored-by: Christina Entcheva <[email protected]>

Author: 4 people

assets/images/help/discussions/discussion-category-form-sample.png

@@ -34,7 +34,8 @@ You can create defaults in your organization{% ifversion fpt or ghes or ghec %}
 Community health file | Description
 --- | ---{% ifversion fpt or ghec %}
 *CODE_OF_CONDUCT.md* | A CODE_OF_CONDUCT file defines standards for how to engage in a community. For more information, see "[Adding a code of conduct to your project](/articles/adding-a-code-of-conduct-to-your-project/)."{% endif %}
-*CONTRIBUTING.md* | A CONTRIBUTING file communicates how people should contribute to your project. For more information, see "[Setting guidelines for repository contributors](/articles/setting-guidelines-for-repository-contributors/)."{% ifversion fpt or ghec %}
+*CONTRIBUTING.md* | A CONTRIBUTING file communicates how people should contribute to your project. For more information, see "[Setting guidelines for repository contributors](/articles/setting-guidelines-for-repository-contributors/)."{% ifversion discussion-category-forms %}
+Discussion category forms | Discussion category forms customize the templates that are available for community members to use when they open new discussions in your repository. For more information, see "[Creating discussion category forms](/discussions/managing-discussions-for-your-community/creating-discussion-category-forms)."{% endif %}{% ifversion fpt or ghec %}
 *FUNDING.yml* | A FUNDING file displays a sponsor button in your repository to increase the visibility of funding options for your open source project. For more information, see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)."{% endif %}
 Issue and pull request templates{% ifversion fpt or ghes or ghec %} and *config.yml*{% endif %} | Issue and pull request templates customize and standardize the information you'd like contributors to include when they open issues and pull requests in your repository. For more information, see "[About issue and pull request templates](/articles/about-issue-and-pull-request-templates/)."{% ifversion fpt or ghes or ghec %}
 *SECURITY.md* | A SECURITY file gives instructions for how to report a security vulnerability in your project. For more information, see "[Adding a security policy to your repository](/code-security/getting-started/adding-a-security-policy-to-your-repository)."{% endif %}

content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md

@@ -0,0 +1,34 @@
+---
+title: Creating discussion category forms
+shortTitle: Create discussion category forms
+intro: 'You can customize the templates that are available for community members to use when they open new discussions in your repository.'
+versions:
+  feature: discussion-category-forms
+---
+
+{% data reusables.discussions.discussion-category-forms-beta %}
+
+## About discussion category forms
+
+You can encourage community members to include specific, structured information in their discussions by using discussion forms in your repository. With discussion category forms, you can create discussion templates that have customizable web form fields. Discussion forms are written in YAML using the {% data variables.product.prodname_dotcom %} form schema. For more information, see "[Syntax for {% data variables.product.prodname_dotcom %}'s form schema](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema)." 
+
+{% data reusables.actions.learn-more-about-yaml %}
+
+To use a discussion category form in your repository, you must create a new file and add it to the  `/.github/DISCUSSION_TEMPLATE/` folder in your repository. 
+
+You can also create discussion category forms for your organization. For more information, see "[Creating a default community health file](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)."
+
+Discussion category forms are not supported for polls. For more information about polls, see "[About polls](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-polls)."
+
+Here is the rendered version of the issue form.
+
+  ![Screenshot of a rendered discussion category form](/assets/images/help/discussions/discussion-category-form-sample.png)
+
+## Creating discussion category forms
+
+People with write access to a repository can create a discussion category form. 
+
+1. Navigate to the repository where you want to create a discussion category form. 
+2. In your repository, create a file called `/.github/DISCUSSION_TEMPLATE/FORM-NAME.yml`, replacing `FORM-NAME` with the name for your discussion category form. {% data reusables.discussions.discussion-category-forms-name %} For more information about creating new files on GitHub, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)."
+3. In the body of the new file, type the contents of your discussion category form. For more information, see "[Syntax for discussion category forms](/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms)."
+4. Commit your file to the default branch of your repository. For more information, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)."

content/discussions/managing-discussions-for-your-community/creating-discussion-category-forms.md

@@ -9,5 +9,7 @@ children:
   - /managing-categories-for-discussions
   - /moderating-discussions
   - /viewing-insights-for-your-discussions
+  - /creating-discussion-category-forms
+  - /syntax-for-discussion-category-forms
 ---
 

content/discussions/managing-discussions-for-your-community/index.md

@@ -0,0 +1,49 @@
+---
+title: Syntax for discussion category forms
+shortTitle: Syntax for discussion category forms
+intro: 'You can use YAML syntax to define the fields in your discussion category forms.'
+versions:
+  feature: discussion-category-forms
+---
+
+{% data reusables.discussions.discussion-category-forms-beta %}
+
+## About YAML syntax for discussion category forms
+
+You can create custom discussion category forms by adding a YAML form definition file to the `/.github/DISCUSSION_TEMPLATE/` folder in your repository. {% data reusables.actions.learn-more-about-yaml %} 
+
+{% data reusables.discussions.discussion-category-forms-name %}
+
+For each field, you can define the input type, validation, and a default label.
+
+When a community member fills out a discussion form, their responses for each input are converted to markdown and added to the body of a discussion. Community members can edit their discussions that were created with a discussion form and other people can interact with the discussion like a discussion created through other methods.
+
+This example YAML configuration file defines a general discussion category form.
+
+{% data reusables.discussions.discussion-category-forms-sample %}
+
+## Top-level syntax
+
+The configuration file for a discussion category form must contain a `body` key, and the `body` must contain at least 1 non-Markdown field.
+
+```YAML{:copy}
+body:
+- type: input
+  id: suggestion
+  attributes:
+    label: Suggestion
+    description: "How might we make this project better?"
+    placeholder: "Adding a CODE_OF_CONDUCT.md file would be a great idea."
+  validations:
+    required: true
+```
+
+You can set the following top-level keys for each issue form.
+
+| Key | Description | Required | Type |
+| :-- | :-- | :-- | :-- | :-- |
+| `body` | Definition of the input types in the discussion form. | Required | Array |
+| `labels` | Labels that will automatically be added to discussions created with this template. | Optional | Array or comma-delimited string |
+| `title` | A default title that will be pre-populated in the discussion submission form. | Optional | String |
+
+To add fields to your form, include an array of form elements in the `body` key. For a list of available elements and their syntaxes, see "[Syntax for {% data variables.product.prodname_dotcom %}'s form schema](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema)."

content/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms.md

@@ -0,0 +1,7 @@
+# Issues 8484
+# Discussions Category Forms - [Public Beta]
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.8'
+  ghae: '>=3.8'

data/features/discussion-category-forms.yml

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** Discussion category forms are currently in limited public beta and subject to change.
+
+{% endnote %}

data/reusables/discussions/discussion-category-forms-beta.md

@@ -0,0 +1 @@
+   The name must correspond with the slug for one of your discussion categories. For example, the template for the "Announcements" category should be `.github/DISCUSSION_TEMPLATE/announcements.yml`. 

data/reusables/discussions/discussion-category-forms-name.md

@@ -0,0 +1,58 @@
+```YAML{:copy}
+title: "[General] "
+labels: ["General Introduction"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is text that will show up in the template!
+  - type: textarea
+  id: improvements
+  attributes:
+    label: Top 3 improvements
+    description: "What are the top 3 improvements we could make to this project?"
+    value: |
+      1.
+      2.
+      3.
+      ...
+    render: bash
+  validations:
+    required: true
+  - type: markdown
+    attributes:
+      value: |
+        ## Markdown header
+        And some more markdown
+  - type: input
+    id: has-id
+    attributes:
+      label: Suggestions
+      description: A description about suggestions to help you
+    validations:
+      required: true
+  - type: dropdown
+  id: download
+  attributes:
+    label: Which area of this project could be most improved?
+    options:
+      - Documentation
+      - Pull request review time
+      - Bug fix time
+      - Release cadence
+  validations:
+    required: true
+  - type: checkboxes
+    attributes:
+      label: Check that box!
+      options:
+        - label: This one!
+          required: true
+        - label: I won't stop you if you check this one, too
+  - type: markdown
+    attributes:
+      value: |
+        ### The thrilling conclusion
+        _to our template_
+      
+```