Create a design review, pull request, or issue template
    • Dark
      Light
    • PDF

    Create a design review, pull request, or issue template

    • Dark
      Light
    • PDF

    Article summary

    Overview

    Design review or issue templates are pre-filled frameworks and content that you can set in advance for any future reviews.

    They are great to:

    • Standardize processes across teams
    • Give new engineers a starting point to help with their training and onboarding
    • Avoid repetitive manual tasks of entering the same information for each new review
    • Reduce the risk of manual and items slipping through the cracks

    Options

    Single design review (pull request) template

    This template is perfect if you need only one template type.

    Design review (pull request) template. New design review page shown, with "write" tab open at the bottom.Steps to create a design review template in Allspice Hub

    1. Navigate to the repository where you'd like to create the review template

    2. In the Files tab, select New File

    Test repository with "file" tab opened.

    3. Create a directory called .allspice

    • Note: You can skip this step if you put the template in the root directory

    4. Create a file called pull_request_template.md

    • Note: AllSpice Hub calls the template using this name, so make sure it's entered properly

    Gif of the creation of the directory, pull_request_template.md is being typed.

    5. Enter your template contents in the New File section using Markdown styling

    Test repo page with new file section opened with content entered using  markdown styling.

    6. Once your template is ready, click Commit Changes at the end

    Bottom of template. Commit changes is shown with a textbox to enter an optional extended description. You can select adding a sign-of-trailer, commit directly to the main branch, or create a new branch. At the very bottom of the page there are two buttons, one says "commit changes", while the other says "cancel".

    Using your design review template

    Going forward, the contents of your template will automatically populate for any new design reviews.

    Gif beginning with clicking new design review, scrolling through the design review template and clicking creat design review once scrolling is done. Then it goes through a design review checklist.

    You can edit your review template by navigating to the file location and selecting Edit File

    In the repo file tab. To the right is edit file


    Multiple design review (pull request) templates

    You may want to use different templates for different phases of the design process, like templates for sch, pcb, BOM, gerber review.

    The interface for multiple templates requires manually adding a query string to the URL, so it may not be the best solution for you.

    If you do want to use multiple design review templates, this is how you do it.

    Adding multiple pull request templates

    Create a folder in your repo called "pull_request_template". You might be able to change the name in the future, but for now it should be this exact folder name.

    Inside the folder, add your individual template files. These can be markdown or yml.


    Using the multiple pull request templates

    By default, the system will load the default pull request at .allspice/pull_request_template.md

    If you want to load one of your multiple pull requests, you add the following query string to your design review when you create it: 

     ?template=pull_request_template%2fnew_template.yml

    Here is the full URL

    https://hub.allspice.io/ExampleOrganization/MultipleIssueTemplatesTest/compare/main...develop?template=pull_request_template%2fnew_template.yml

    Multiple Issue Templates

    Using multiple issue templates is much easier, as we have deployed a front end GUI interface for selecting the issue template.


    Creating issue templates

    Create a folder in your repo root directory called "issue_template".

    Add your issue template files. These can be in markdown or yml.


    Using your multiple issue templates

    Simply navigate to your repo issue tab and click New Issue. You will be presented with a list of templates to choose from.List of templates in issue tab including bug report, new component request, issue template - default, and default.Here is an example of a new component request template.

    Component request template example.

    Syntax for markdown template

    <span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">---
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">name: "Template Name"
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">about: "This template is for testing!"
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">title: "[TEST] "
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">ref: "main"
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">labels:
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; color: rgb(102, 217, 239);">-</span> bug
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; color: rgb(102, 217, 239);">-</span> "help needed"
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">---
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">
    </span></span><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit; display: flex;"><span style="outline: none; box-sizing: inherit; font-style: inherit; font-weight: inherit;">This is the template!
    </span></span>

    In the above example, when a user is presented with the list of issues they can submit, this would show as Template Name with the description This template is for testing!. When submitting an issue with the above example, the issue title would be pre-populated with [TEST] while the issue body would be pre-populated with This is the template!. The issue would also be assigned two labels, bug and help needed, and the issue will have a reference to main.


    Syntax for yaml template

    This example YAML configuration file defines an issue form using several inputs to report a bug.


    name: Bug Report
    about: File a bug report
    title: "[Bug]: "
    body:
      - type: markdown
        attributes:
          value: |
            Thanks for taking the time to fill out this bug report!        
      - type: input
        id: contact
        attributes:
          label: Contact Details
          description: How can we get in touch with you if we need more info?
          placeholder: ex. email@example.com
        validations:
          required: false
      - type: textarea
        id: what-happened
        attributes:
          label: What happened?
          description: Also tell us, what did you expect to happen?
          placeholder: Tell us what you see!
          value: "A bug happened!"
        validations:
          required: true
      - type: dropdown
        id: version
        attributes:
          label: Version
          description: What version of our software are you running?
          options:
            - 1.0.2 (Default)
            - 1.0.3 (Edge)
        validations:
          required: true
      - type: dropdown
        id: browsers
        attributes:
          label: What browsers are you seeing the problem on?
          multiple: true
          options:
            - Firefox
            - Chrome
            - Safari
            - Microsoft Edge
      - type: textarea
        id: logs
        attributes:
          label: Relevant log output
          description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
          render: shell
      - type: checkboxes
        id: terms
        attributes:
          label: Code of Conduct
          description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
          options:
            - label: I agree to follow this project's Code of Conduct
              required: true

    Markdown

    You can use a markdown element to display Markdown in your form that provides extra context to the user, but is not submitted.

    Attributes:

    KeyDescriptionRequiredTypeDefaultValid values
    valueThe text that is rendered. Markdown formatting is supported.RequiredString--

    Textarea

    You can use a textarea element to add a multi-line text field to your form. Contributors can also attach files in textarea fields.

    Attributes:

    KeyDescriptionRequiredTypeDefaultValid values
    labelA brief description of the expected user input, which is also displayed in the form.RequiredString--
    descriptionA description of the text area to provide context or guidance, which is displayed in the form.OptionalStringEmpty String-
    placeholderA semi-opaque placeholder that renders in the text area when empty.OptionalStringEmpty String-
    valueText that is pre-filled in the text area.OptionalString--
    renderIf a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing.OptionalString-Languages known to Gitea.

    Validations:

    KeyDescriptionRequiredTypeDefaultValid values
    requiredPrevents form submission until element is completed.OptionalBooleanfalse-

    Input

    You can use an input element to add a single-line text field to your form.

    Attributes:

    KeyDescriptionRequiredTypeDefaultValid values
    labelA brief description of the expected user input, which is also displayed in the form.RequiredString--
    descriptionA description of the field to provide context or guidance, which is displayed in the form.OptionalStringEmpty String-
    placeholderA semi-transparent placeholder that renders in the field when empty.OptionalStringEmpty String-
    valueText that is pre-filled in the field.OptionalString--

    Validations:

    KeyDescriptionRequiredTypeDefaultValid values
    requiredPrevents form submission until element is completed.OptionalBooleanfalse-
    is_numberPrevents form submission until element is filled with a number.OptionalBooleanfalse-
    regexPrevents form submission until element is filled with a value that match the regular expression.OptionalString-a regular expression

    You can use a dropdown element to add a dropdown menu in your form.

    Attributes:

    KeyDescriptionRequiredTypeDefaultValid values
    labelA brief description of the expected user input, which is displayed in the form.RequiredString--
    descriptionA description of the dropdown to provide extra context or guidance, which is displayed in the form.OptionalStringEmpty String-
    multipleDetermines if the user can select more than one option.OptionalBooleanfalse-
    optionsAn array of options the user can choose from. Cannot be empty and all choices must be distinct.RequiredString array--

    Validations:

    KeyDescriptionRequiredTypeDefaultValid values
    requiredPrevents form submission until element is completed.OptionalBooleanfalse-

    Checkboxes

    You can use the checkboxes element to add a set of checkboxes to your form.

    Attributes:

    KeyDescriptionRequiredTypeDefaultValid values
    labelA brief description of the expected user input, which is displayed in the form.RequiredString--
    descriptionA description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting.OptionalStringEmpty String-
    optionsAn array of checkboxes that the user can select. For syntax, see below.RequiredArray--

    For each value in the options array, you can set the following keys.

    KeyDescriptionRequiredTypeDefaultOptions
    labelThe identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks.RequiredString--
    requiredPrevents form submission until element is completed.OptionalBooleanfalse-

    Was this article helpful?