160 строки
7.6 KiB
Markdown
160 строки
7.6 KiB
Markdown
# Bug Report Reproduction Guide
|
|
|
|
First of all, thank you for reporting this potential bug. Nobody likes bugs
|
|
and to help us diagnose and resolve your potential issue as effective and
|
|
quickly as possible, we would like to give you a bit more information about
|
|
why we ask you for a reproducible example of the problem, and how to provide
|
|
one.
|
|
|
|
## What is a reproduction?
|
|
|
|
A reproduction, reproducible example or just repro for short is the most basic
|
|
code to demonstrate the issue that you're seeing. It's the simplest way to
|
|
reproduce the issue. Ideally, you should be able to reproduce the issue by
|
|
just running the code in the project you have provided and see the problem. If
|
|
any reproduction steps are needed, either note them in the issue or include
|
|
them in the project somehow.
|
|
|
|
## Why do we ask for a reproducible example?
|
|
|
|
Depending on your project a codebase can be pretty big. The bigger your
|
|
project, the more factors that can be of influence on a bug or issue that you
|
|
might be seeing.
|
|
|
|
In order to be sure that this is something that is happening in the Apple SDKs
|
|
for .NET and not something in your code (or a combination of these things), it
|
|
is super helpful to have a small sample that reproduces the issue. This way we
|
|
can:
|
|
|
|
* better pinpoint the source of the issue
|
|
* therefore, we can fix the issue faster
|
|
* and we can make sure that the issue is not a false positive
|
|
|
|
It also acts as a double-edged sword. When you take your code apart
|
|
piece-by-piece in a new project, adding things back one by one, it will become
|
|
very clear what different factors are at play here and you might discover that
|
|
the issue might be something in your code. At the very least you will be able
|
|
to provide a very detailed description of what you're seeing. That helps us
|
|
get to the cause faster and resolve the issue quicker.
|
|
|
|
### I just want to report a bug, why do you want a reproduction?
|
|
|
|
We hear this a lot. We understand you're busy, we're all busy! A reproduction
|
|
is not just about pleasing us or you doing our work. As already mentioned
|
|
above, it will help you get a better understanding of where the issue is
|
|
exactly. We've seen lots of cases where people realized, through a
|
|
reproduction, that the solution was right within their reach. Regardless of it
|
|
being a bug in this .NET SDK or not.
|
|
|
|
We like to see this as a team effort.
|
|
|
|
#### But I don't have time for this!
|
|
|
|
Please help us, help you! This is an open-source project under the MIT
|
|
license. We care about our project and therefore by extension also about your
|
|
project. But realize that when you come onto our repo, maybe frustrated
|
|
because things are not working and you just drop a one-liner, no reproduction,
|
|
mentioning that you don't have the time, that's also not very motivating for
|
|
us. On the other end of these GitHub issues are still people. People that are
|
|
doing their best to move this project forward, people that do not enjoying
|
|
seeing you being blocked.
|
|
|
|
Also consider how that comes across. If you don't have the time to report in
|
|
detail what is going on, then really how important is the issue? If this is
|
|
really important and blocking you, it would seem to make sense to prioritize
|
|
getting us all the details to help resolve this faster. We are all here to
|
|
help you. But remember that we don't know your project and we don't know any
|
|
details, please help us understand and be nice.
|
|
|
|
## How to provide a reproduction project?
|
|
|
|
With a reproduction we want to rule out a couple of things:
|
|
|
|
* The issue is not in your code, but in the iOS/tvOS/macOS/Mac Catalyst SDKs for .NET.
|
|
* The issue has not been already resolved in the latest version of the SDK.
|
|
|
|
Therefore we would like to propose the following steps to create a reproduction sample:
|
|
|
|
* Check if you are using the latest version of the .NET workloads and you can
|
|
still reproduce the issue.
|
|
* If yes, please check any available preview versions and see if you can
|
|
reproduce the issue.
|
|
* If you still can, please check to see if there are is an issue already
|
|
opened on the repository for it:
|
|
* If there is, see if you can add any more detail about your specific case,
|
|
that might help to resolve it quicker. If you don't have any additional
|
|
information, add an emoji to the first post of the issue so we know how
|
|
many people are impacted by this.
|
|
* When in doubt, always file a new issue. It's much easier to mark an issue
|
|
as a duplicate of another, than it is to split an issue into two (or more)
|
|
isssues after an extensive conversation in the issue that effectively
|
|
derailed the original issue because it turned out to be something
|
|
unrelated.
|
|
* If there is no issue for it yet, please open one and provide detailed
|
|
answers to everything in the New Issue form.
|
|
|
|
At this point we would love for you to include the reproduction.
|
|
|
|
* Start with a File > New .NET iOS / tvOS / macOS / Mac Catalyst project, in
|
|
other words, a clean, new project. Make sure that you are using the last
|
|
version of the .NET workloads.
|
|
* Start extracting the code from your project, piece-by-piece, until you have
|
|
reached the issue.
|
|
* Try to remove some code or make small changes to see how that influences the
|
|
issue you're seeing. Remove any code that is not needed to reproduce the
|
|
issue. This is noise and will interfere with getting to a cause and
|
|
solution.
|
|
* Put the code on a GitHub repository and include that link in the issue that
|
|
you're opening.
|
|
* Get a [binary build log][1] and attach that to the issue as well.
|
|
|
|
> **Warning**
|
|
>
|
|
> **We can't accept any zip files attached to the issue.** If we need the code
|
|
> in a zip, we can get that from the GitHub repository. This will also make it
|
|
> easier to collaborate. If we think we spot something that doesn't look
|
|
> right, we can open a PR on your repro repo (😬) and you can easily see the
|
|
> differences.
|
|
|
|
## Why can't you just download my zip file reproduction?!
|
|
|
|
While we've never had problems with this, it is still a potential attack
|
|
vector for hackers and other malicious people. Even unzipping a zip file could
|
|
execute code, let alone load code into Visual Studio that we could not
|
|
(easily) look at before opening it. Because we value your safety and privacy
|
|
as well as our own, we want to make sure that none of this can happen.
|
|
|
|
Also, by putting it in a GitHub repo it's easier to potentially collaborate.
|
|
We (and our amazing community!) can comment on a piece of code right then and
|
|
there and help you further. It can even serve as a nice example for other
|
|
people!
|
|
|
|
If you don't like to have a lot of repos, you could opt for a repo where on
|
|
the `main` branch you put a File > New Project, and from there create branches
|
|
for different issues.
|
|
|
|
## Big don'ts!
|
|
|
|
- Never put any sensitive information in your code. No API keys, credentials,
|
|
personal information, etc.
|
|
- Never put any propriatary code in your reproduction. We are contractually
|
|
not allowed to look at code that you do not own without big legal hassles
|
|
and NDA's, that's not fun for anyone.
|
|
- Never submit binaries (mostly covered by putting it on a GitHub repo)
|
|
- Do not reference external data-sources, this should rarely be needed.
|
|
- Always refer to concrete version numbers. Avoid saying "this happens in the
|
|
latest version". We don't know if you're using a preview version or maybe
|
|
you _think_ you're using the latest version but actually aren't. To avoid
|
|
any confusion, always refer to exact version numbers.
|
|
|
|
# That's it!
|
|
|
|
The first time might take you a bit longer to go through all this, but once
|
|
you've done it you'll see it isn't that much more work and it will benefit the
|
|
process a lot.
|
|
|
|
Thank you so much for taking some of your valuable time to make .NET MAUI the
|
|
best version it can be! We really appreciate it.
|
|
|
|
[1]: https://github.com/xamarin/xamarin-macios/wiki/Diagnosis#binary-build-logs
|