From dd0e8e51c100ac1c84f83e48f8011c27dd82c76c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elian=20=E2=98=95=EF=B8=8F?= Date: Fri, 7 Apr 2023 08:10:53 +0200 Subject: [PATCH] add minimal examples guide (#2978) Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Dan Jutan Co-authored-by: Sarah Rainsberger --- .../docs/en/guides/troubleshooting.mdx | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/content/docs/en/guides/troubleshooting.mdx b/src/content/docs/en/guides/troubleshooting.mdx index b811f013ca3e1..7bc249d2df16a 100644 --- a/src/content/docs/en/guides/troubleshooting.mdx +++ b/src/content/docs/en/guides/troubleshooting.mdx @@ -199,6 +199,33 @@ const answer = sum(2, 4); ``` +## Creating minimal reproductions + +When troubleshooting your code, it can be helpful to create a **minimal reproduction** of the issue that you can share. This is a smaller, simplified Astro project that demonstrates your issue. Having a working reproduction in a new project helps to confirm that this is a repeatable problem, and is not caused by something else in your personal environment or existing project. + +Sharing a minimal reproduction is helpful when asking for help in our support threads and is often required when filing a bug report to Astro. + +### Create a StackBlitz via [astro.new](https://astro.new) + +You can use [astro.new](https://astro.new) to create a new Astro project with a single click. For minimal reproductions, we strongly recommend starting from the minimal (empty) example running in [StackBlitz](https://stackblitz.com), with as little extra code as possible. + +StackBlitz will run this Astro project in the browser, outside of your local environment. It will also provide you with a shareable link so that any Astro maintainer or support squad member can view your minimal reproduction outside of their own local environment. This means that everyone is viewing the exact same project, with the same configuration and dependencies. This makes it easy for someone else to help troubleshoot your code. If the issue is reproducable, it allows you to verify that the issue lies within the Astro code itself and you can feel confident submitting a bug report. + +Note that not every issue is reproducable in StackBlitz. For example, your issue might be dependent on a specific environment or package manager, or it may involve HTML Streaming, which isn't supported in StackBlitz. In this case, create a new minimal (empty) Astro project using the CLI, reproduce the issue, and upload it to a GitHub repository. Instead of sharing a StackBlitz URL, provide a link to the GitHub repository of your minimal reproduction. +### Minimal code + +Once your empty project is set up, go through the steps to reproduce the issue. This can include adding packages, changing configuration, and writing code. + +You should only add the minimum amount of code necessary to reproduce the issue. Do not reproduce other elements of your existing project, and remove all code that is not directly related to the issue. + +### Create an issue + +If your issue can be reproduced, then it is time to create an issue and file a bug report! + +Go to the appropriate Astro repository on GitHub and open a new issue. Most repositories have an issue template that will ask questions or require information in order to submit. It's important that you follow these templates because if you don't provide the information we need, then we have to ask you for it... and no one is working on your issue! + +Include the link to your minimal reproduction on StackBlitz (or GitHub repository, if necessary). Start with a description of the expected versus actual behavior to provide context for the issue. Then, include clear, step-by-step instructions on how to replicate the issue in an Astro project. + ## Need more? Come and chat with us on [Discord](https://astro.build/chat) and explain your issue in the `#support-threads` channel. We’re always happy to help!