How to create good issues
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
- Fill out all sections (and remove guidance)
- Include context
- Use markdown formatting
- Use code formatting (inline & blocks)
- Referencing additional materials
Every issue is unique, but it doesn't mean that it hasn't been experienced by someone else before you.
We've tried to make it easy for anyone to look for previous issues related to a sample by adding a link in the Help section, which is located at the bottom of every sample README.md.
Please take a look at prior issues; you may be able to provide additional information that will help resolve your issue. Who knows, you may not even need to open a new issue!
We know it can be frustrating to create issues. It is also frustrating for people who are trying to help you when there isn't information to be able to do anything.
The easiest way to create an issue is to use one of the links in the Help section, which is located at the bottom of every sample README.md.
Doing so will automatically provide the start of the title, the @mention the authors, and tag the issue with the appropriate label.
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.
- start with the name of the sample
- ensure the title is descriptive of the title
- be concise with the title
- use short titles that don't explain the issue
- use the title field to post the error
Our issue templates use fillable "forms" with clearly-indicated mandatory fields in each section.
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 -- or don't fill them with the appropriate information -- 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.
- 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))
- 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
Most issue types will ask you to @mention the author(s). Don't skip this step!
When you create an issue, the original authors of the sample don't just happen to know that you created an issue. There's no automated way to notify them unless you @mention them.
And simply listing their name doesn't work either; you need to enter their GitHub username, preceded by "@".
For example, if you're creating an issue for a web part authored by Hugo Bernier, entering Hugo Bernier won't help you; you need to enter @hugoabernier to make sure that he gets notified about the issue.
Please note that Hugo Bernier helps manage the repository. Do not @mention him unless he is one of the authors -- listed under Authors.
You can find the authors for a sample by looking at that sample's README.md, in the Solution section under Authors.
NOTE: Make sure that you don't just look at the sample's GitHub history; the repository's maintainers are often the last people to modify the sample's files, but they're not the authors. If you don't provide the right authors, we'll tag the issue with the status:wrong-author label and ask you to provide the correct authors before we can help you further.
There as so many notifications from GitHub that it can be impossible for authors to realize that an issue relates to their sample unless they are @mentionned. Out of respect to other members of the community and to keep the list of issues easy to manage, we automatically close issues that do not properly @mention authors, because such issues are most likely to remain unresolved until they are closed due to lack of activivities.
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
The bug template requires you to paste the json results of a recent spfx doctor to help eliminate issues related to incompatibilities. If you don't know how to do so, follow these steps
Keep in mind that the purpose of this repository is to help SPFx developers learn and share code patterns. We ask that everyone creating issues apply a modicum of efforts to investigate the issues and learn from the issues.
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:
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 to 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).
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.
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 |
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!
- include a link to a public repo of your project
- include screenshots (you can paste an image inline into an issue)
- attach a ZIP or a link to a ZIP in the issue (no one will download it for fear of viruses or malware)