From e63cd5a55a3da47b6f2b94f461d66acf5480a3f1 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 1 Jan 2023 17:21:59 +0100 Subject: [PATCH] Finished first version of bug report guide --- docs/bug-report/index.md | 197 +++++++++++++++++++++++++++++--------- docs/reference/buttons.md | 2 +- mkdocs.yml | 2 +- 3 files changed, 153 insertions(+), 48 deletions(-) diff --git a/docs/bug-report/index.md b/docs/bug-report/index.md index ff3bcdc56..15c2f53b5 100644 --- a/docs/bug-report/index.md +++ b/docs/bug-report/index.md @@ -1,51 +1,50 @@ # Bug reporting Material for MkDocs is an actively maintained project that we constantly strive -to improve. With a project of this size and complexity, :material-bug: bugs may -occur. If you think you have discovered a bug, you can help us by reporting an -issue in our public [issue tracker]. +to improve. With a project of this size and complexity, bugs may occur. If you +think you have discovered a bug, you can help us by submitting an issue in our +public [issue tracker]. [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues ## Before creating an issue -With more than 20.000 users, issues are raised almost every day. The maintainers +With more than 20.000 users, issues are created every other day. The maintainers of this project are trying very hard to keep the number of open issues down by -fixing bugs as fast as possible. High quality and complete bug reports enable us -to help you much faster. +fixing bugs as fast as possible. By following this guide, you will know exactly +what information we need to help you quickly. -__Please make sure to try the following things before creating an issue__. +__But first, please try the following things before creating an issue.__ ### Upgrade to latest version Chances are, that the bug you discovered was already fixed in a subsequent -version. Thus, before reporting an issue, please ensure that you're running the +version. Thus, before reporting an issue, ensure that you're running the [latest version] of Material for MkDocs. Please consult our [upgrade guide] to learn how to upgrade to the latest version. !!! warning "Bug fixes are not backported" - Please understand that only issues that occur in the latest version of + Please understand that only bugs that occur in the latest version of Material for MkDocs will be addressed. Also, in order to reduce duplicate - efforts, fixes are not backported to earlier versions. + efforts, fixes cannot be backported to earlier versions. ### Remove customizations -If you're using [customizations] like [additional CSS] and [JavaScript], or +If you're using [customizations] like [additional CSS], [JavaScript], or [theme extension], please remove them from `mkdocs.yml` before reporting a bug. -__We can't offer official support for bugs that might hide in your overrides__, -so please remove the following settings from `mkdocs.yml`: +We can't offer official support for bugs that might hide in your overrides, so +make sure to omit the following settings from `mkdocs.yml`: - [`theme.custom_dir`][theme.custom_dir] - [`theme.hooks`][theme.hooks] - [`extra_css`][extra_css] - [`extra_javascript`][extra_javascript] -If after removing those settings, the bug is gone, the bug is likely caused by +If, after removing those settings, the bug is gone, the bug is likely caused by your customizations. A good idea is to add them back gradually to narrow down -the root cause. Don't be shy to ask on our [discussion board] or -[:simple-stackoverflow: StackOverflow][StackOverflow] for help if you're running -into problems. +the root cause of the problem. If you did a major version upgrade, make sure you +adjusted all partials you have overridden. !!! warning "Customizations mentioned in our documentation" @@ -54,6 +53,9 @@ into problems. our documentation explicitly mentions], you are of course encouraged to report it. +__Don't be shy to ask on our [discussion board] for help if you run into +problems.__ + [latest version]: ../changelog/index.md [upgrade guide]: ../upgrade.md [Customizations]: ../customization.md @@ -70,10 +72,50 @@ into problems. ### Search for solutions -TBD +At this stage, we know that the problem persists in the latest version and is +not caused by any of your customizations. However, it's possible that the issue +might be the result of a small typo or a syntactical error in a configuration +file, e.g. `mkdocs.yml`. -- Documentation -- Open issues +Now, before you go through the trouble of creating a bug report, that we +maintainers close right away with a link to the relevant documentation section +or another already reported or closed issue or discussion, you can save time for +us and yourself by doing some research: + +1. [Search our documentation] and look for the relevant sections that might + possibly be related to your problem. If found, make sure that you configured + everything correctly.[^1] + + [^1]: + When adding lines to `mkdocs.yml`, make sure you are preserving the + indentation as mentioned in the documentation, since YAML is a + whitespace-sensitive language. Many reported issues turn out to be + configuration errors. + +2. [Search our issue tracker][issue tracker], as another user might already + have reported the same problem, and there might even be a known workaround + or fix for it. Thus, no need to create a new issue. + +3. [Search our discussion board][discussion board] to learn if other users + are struggeling with similar problems, and work together with our + great community towards a solution. Many problems are solved here. + +__Keep track of all search terms and relevant links, you'll need +them in the bug report.__[^2] + + [^2]: + We might be using terminology in our documentation different from yours, + but mean the same. When you include the search terms and related links + in your bug report, you help us to adjust and improve the documentation. + +--- + +At this point, when you still haven't found a solution to your problem, we +encourage you to create an issue, because it's now very likely that you +stumbled over something we don't know yet. Read the next section to learn +how to create a complete and helpful bug report. + + [Search our documentation]: ?q= ## Issue template @@ -108,7 +150,7 @@ can be inferred from the title. | | Example | | -------- | -------- | -| :material-check:{ style="color: #4DB6AC" } __Good__ | Built-in `typeset` plugin changes precedence of nav title over `h1` +| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1` | :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline | :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work | :material-close:{ style="color: #EF5350" } __Generic__ | Please help @@ -117,8 +159,8 @@ can be inferred from the title. Before describing the bug, you can provide additional context that can be helpful to understand what you were trying to achieve. Explain the circumstances -in which you're using Material for MkDocs. Don't write about the bug itself or -anything related. +in which you're using Material for MkDocs, and what you _think_ might be +relevant. Don't write about the bug here. > __Why this might be helpful__: some errors only manifest in specific settings, > environments or edge cases, for example when your documentation contains @@ -129,25 +171,25 @@ anything related. Now, to the bug you want to report. Provide a clear, focused, specific and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported to Material for MkDocs, and not to one of its -[dependencies]. Guideline for descriptions: +[dependencies]. Adhere to the following principles: - __Explain the what, not the how__ – don't explain [how to reproduce the bug][Steps to reproduce] here, we're getting there. Focus on articulating the problem and its impact as clearly as possible. - __Keep it short and concise__ – if the bug can be precisely explained in one - or two sentences, perfect. Don't inflate it – the maintainers and users - reading your words will be grateful. + or two sentences, perfect. Don't inflate it – maintainers and future users + will be grateful, having to read less. -- __One :material-bug: bug at a time__ – if you encountered several unreleated - bugs, please open an issue for each of them. Don't report them all in the - same issue, as this makes communication difficult. +- __One bug at a time__ – if you encountered several unrelated bugs, please + create separate issues for them. Don't report them in the same issue, as + this makes attribution difficult. --- -__Stretch :material-run-fast: goal__ – if you found a workaround or a way to fix +:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix the bug, you can help other users to temporarily mitigate the problem before -Material for MkDocs fixes the bug in its code base. +we maintainers can fix the bug in our code base. > __Why we need this__: in order for us to understand the issue at hand, we > need a clear description of the problem and its impact, which is essential @@ -157,42 +199,105 @@ Material for MkDocs fixes the bug in its code base. ### Related links -Of course, prior to reporting a bug, you have read our documentation and could -not find a working solution. Please share links to all sections of our -documentation that might be relevant to the bug, as it helps us gradually -improve it. +Of course, prior to reporting a bug, you have read our documentation and +[could not find a working solution][search for solutions]. Please share links +to all sections of our documentation that might be relevant to the bug, as it +helps us gradually improve it. Additionally, since you have searched our [issue tracker] and [discussion board] before reporting an issue, and have possibly found several issues or discussions, include those as well. Every link to an issue or discussion creates -a backlink, guiding us maintainers and future users. +a backlink, guiding us maintainers and other users in the future. + +--- + +:material-run-fast: __Stretch goal__ – if you also include the search terms you +used when [searching for a solution][search for solutions] to your problem, you +make it easier for us maintainers to improve the documentation. > __Why we need this__: related links help us better understand what you were > trying to achieve and whether sections of our documentation need to be > adjusted, extended or overhauled. + [search for solutions]: #search-for-solutions + ### Reproduction -TBD +A minimal reproduction is at the heart of every well-written bug report, as +it allows us maintainers to quickly recreate the necessary conditions to inspect +the bug and quickly find its root cause. It's proven fact that issues with +concise and small reproductions can be fixed much faster. + +[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary } + +--- + +After you created the reproduction, you should have a .zip file, ideally not +larger than 1 MB. Just drag and drop the .zip file into this field, which will +automatically upload it to GitHub. + +> __Why we need this__: if an issue contains no minimal reproduction, or just +> a link to a repositority with thousands of files, the maintainers would need +> to invest a lot of time into trying to recreate the right conditions to even +> inspect the bug, let alone fix it. + +!!! warning "Don't share links to repositories" + + While we know that it is good practice among developers to include a link + to a repository with the bug report, we currently don't support those in our + process. The reason is that the reproduction that is automatically + produced by the [built-in info plugin] contains all of the necessary + environment information that is often forgotten to be included. + + Additionally, there are many non-technical users of Material for MkDocs that + have trouble creating repositories. + + [Create reproduction]: reproduction.md + [built-in info plugin]: reproduction.md#built-in-info-plugin ### Steps to reproduce -TBD +At this point, you provided us with enough information to understand the bug, +and you gave us a reproduction that we can run and inspect. However, when we +run your reproduction, it might not be immediately apparent how we can see +the bug in action. + +Next, please list the specific steps we should follow when running your +reproduction to observe the bug. Keep the steps short and concise and make sure +to not leave anything out. Use simple language as you would explain it to a five +year old and focus on continuity. + +> __Why we need this__: we must know how to navigate your reproduction in order +> to observe the bug, as some bugs only occur at certain viewports or in +> specific conditions. ### Browser optional { #browser } -TBD +If you're reporting a bug that only happens in one or more _specific_ browsers, +we need to know which browsers are affected. This field is optional, as it is +only relevant when the bug you are reporting does not involve a crash when +[previewing] or [building] your site. + +> __Why we need this__: some bugs only occur in specific browsers or versions. +> Since now, almost all browser are evergreen, we usually don't need to know the +> version in which it occurs, but we might ask for it later. When in doubt, add +> the browser version as the first step in the field above. + + [previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write + [building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site ### Checklist -TBD +Thanks for following the guide, and creating a high quality and complete bug +report – you are almost done. This section ensures that you have read this guide +and have worked to your best knowledge to provide us with everything we need to +know to help you. -## General - -### Dependencies - -TBD +__We'll take it from here.__ ## Incomplete issues -TBD +Please understand, that we reserve us the right to close incomplete issues which +do not contain minimal reproductions, or do not adhere to the quality standards +and requirements mentioned in this document. We will try our best to help you +improve your bug report in the comments. diff --git a/docs/reference/buttons.md b/docs/reference/buttons.md index 72b8dcbc7..963c70e1b 100644 --- a/docs/reference/buttons.md +++ b/docs/reference/buttons.md @@ -1,5 +1,5 @@ --- -icon: material/gesture-tap-button +icon: material/button-cursor --- # Buttons diff --git a/mkdocs.yml b/mkdocs.yml index e20f24937..d3518c684 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -168,7 +168,7 @@ nav: - License: license.md - Bug reporting: - bug-report/index.md - - How to create a reproduction: bug-report/reproduction.md + - Creating a reproduction: bug-report/reproduction.md - Changelog: - changelog/index.md - How to upgrade: upgrade.md