Skip to content

How to Create Good Issues

Jump to bottom
Hugo Bernier edited this page Apr 28, 2021 · 1 revision

Put quite simply: the easier it is to read & understand your issue, the easier it is to help or address the issue. This page will guide you to create a good issue that the community will want to engage with you on!

Create a good title

The title of an issue is one of two things people will see when they are scanning the list of issues. The other (labels) are covered on this page. Titles are also the only things that appear when the issue is referenced in another issue or in a pull request.

A good title is one where a reader can get the general idea of a list

There's a balance: don't be too wordy, but provide enough detail so someone can quickly understand the point of your issue.

Do...

  • ensure the title is descriptive of the title
  • be concise with the title

Don't...

  • use short titles that don't explain the issue
  • use the title field to post the error

Fill out all sections (and remove guidance)

New issues start with a template of sections. These sections are there for a reason... you need to fill them out. Each one contains some guidance in a blockquote on how to use it.

If you ignore the sections, it will delay someone addressing your post in the best situation. In the worst situation, there's a good chance we'll tag the issue with the type:incomplete-issue label and ask you to provide additional detail before someone can move forward on it.

These sections aren't there to make it hard to create issues. They are there to help you provide enough information for your issue so someone can efficiently address it.

Do...

  • fill out all requested information in each section
  • delete the blockquote "helper" text (it starts with >)
  • if applicable, include code snippets in the issue (properly formatted as covered in the section Use code formatting (inline & blocks))

Don't...

  • ignore the sections and post your issue at will
  • leave the "helper" text - it serves no use in the issue other than helping you create a good issue

Include context

Building off the section Fill out all sections (and remove guidance), please provide as much context about your issue as possible. We'll almost always ask for context when you submit an issue that's an error or bug report.

Bug reports & generic issues have a section for Environment details... please ensure you complete this section by adding / removing what we've provided. We're specificaly interested in:

  • OS: e.g. Windows 10, MacOS 10.15.x
  • Framework: e.g. .NET Framework v3.x, .NET Core v3.x, Node.js v6/v8/v10/v12
  • Browser(s): e.g. Chrome v79, Safari v22, FireFox v31, IE v11, Edge, Chromium Edge v79
  • Tooling: e.g. VS Code, SPFx v1.10.0, Visual Studio 2019

Use markdown formatting

The easier it is to read your issue, the easier and quicker it is for someone to help. Richly formatted content is much easier to read when you want to apply emphasis, highlights, and other formatting.

Refer to the following GitHub help docs for details on formatting your issues:

Use code formatting (inline & blocks)

When including code in your issue, please use GitHub's code formatting syntax. Formatted code makes it not only easier to read but helps the person looking at your issue help you quicker.

There are two types of code formatting: inline code & block code. GitHub's help docs have some information on these (Creating and Highlighting Code Blocks).

Inline code

Surround the code with a single back-tick: `. For example, the following...

`var message = "hello world";`

... will be rendered as:

var message = "hello world";

Inline code is intended for a single line, not multiple lines of code. Using it for a block of code makes the code unreadable. For example, the following:

`{
  "bundles": {
    "hello-world-web-part": {
      "components": [
        {
          "entrypoint": "./lib/webparts/helloWorld/HelloWorldWebPart.js",
          "manifest": "./src/webparts/helloWorld/HelloWorldWebPart.manifest.json"
        }
      ]
    }
  }
}`

... will get rendered as:

`{ "bundles": { "hello-world-web-part": { "components": [ { "entrypoint": "./lib/webparts/helloWorld/HelloWorldWebPart.js", "manifest": "./src/webparts/helloWorld/HelloWorldWebPart.manifest.json" } ] } } }`

Please don't do this... instead use fenced code blocks.

Code blocks (multiple lines of code)

Blocks of code should have three back-ticks on the line before and after the code. This is referred to as fenced code.

Refer to the GitHub help for creating fenced code blocks: Creating and Highlighting Code Blocks: Fenced code blocks

If you include the code language identifier, GitHub will apply syntax formatting. The following languages are the most popular in this repo:

Language Language identifier
C# csharp
Command line console
HTTP http
JavaScript javascript
JSON json
TypeScript typescript
XML xml

Referencing additional materials

Feel free to reference additional materials external to your issue, such as projects, images, log files, etc. Anything that helps with your issue is welcomed!

Do

  • include a link to a public repo of your project
  • include screenshots (you can paste an image inline into an issue)

Don't

  • attach a ZIP or a link to a ZIP in the issue (no one will download it for fear of viruses or malware)
Clone this wiki locally