OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Finished first version of bug report guide

Browse Source
This commit is contained in:
squidfunk 2023-01-01 17:21:59 +01:00
parent 54ce87af4a
commit e63cd5a55a
3 changed files with 153 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
docs/bug-report/index.md
View File

@ -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 <u>search terms</u> and <u>relevant links</u>, 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 <u>what</u>, not the <u>how</u>__ – 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 <small>optional</small> { #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.

2
docs/reference/buttons.md
View File

@ -1,5 +1,5 @@
---
icon: material/gesture-tap-button
icon: material/button-cursor
---
# Buttons

2
mkdocs.yml
View File

@ -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