diff --git a/docs/development/minimal-reproductions.md b/docs/development/minimal-reproductions.md index 56dbd939796442e897e006e804404253e348643d..8ed9259f1a297e631f6236507603afa1f9199c2c 100644 --- a/docs/development/minimal-reproductions.md +++ b/docs/development/minimal-reproductions.md @@ -2,7 +2,11 @@ We may ask you to create a "minimal reproduction" repository to help us fix bugs or work on a feature. -This document explains why we need a minimal reproduction, why we won't use your production repository to debug, and how to create a good minimal reproduction. +This document explains: + +- why we need a minimal reproduction +- why we will not use your production repository to debug +- how to create a good minimal reproduction ## Help yourself by creating a minimal reproduction @@ -16,37 +20,39 @@ It's fastest if you - as the bug reporter or feature requester - create the repr ## How the Renovate developers use your minimal reproduction -The first benefit of a public reproduction is to prove that the problem is not caused by your environment or by a setting you left out of your description, thinking it wasn't relevant. -If there were any doubts about whether you'd found a genuine problem before, they are usually removed once a reproduction is made. +A reproduction confirms the problem is with Renovate, and _not_ with your environment, or your configuration settings. +A reproduction also helps us see where the bug or missing feature is, and to verify that the new code meets the requirements. -Next, when a reproduction has minimal config, it can often let us narrow down or even identify the root cause, suggest workarounds, etc. -This means we can often help you from code inspection alone. +When a reproduction has minimal config, we can oftern narrow down, or identify the root cause. +This helps us suggest workarounds. +Often we can help you from code inspection alone. -Finally, by making the code/dependencies minimal, it usually makes the problem feasible to step through using a debugger if code inspection wasn't sufficient. -Production repositories or non-minimal reproductions are often very difficult to debug because break points get triggered dozens or hundreds or times. +Finally, with minimal code and dependencies, we can step through with a debugger. +This helps when looking at the code is not enough to find the problem. +Production repositories, or non-minimal reproductions, are hard to debug as break points get triggered often. ## What is a minimal reproduction? -The basic idea of a minimal reproduction is to use the _least_ amount of both code and config to trigger missing or wrong behavior. -A minimal reproduction helps the developers see where the bug or missing feature is, and allows us to verify that the new code meets the requirements. +A minimal reproduction should have the _least_ amount of both code and config to trigger missing or wrong behavior. ## Where to host the minimal reproduction -Unless it's impossible, use a public repository on GitHub.com to host your reproduction. -If the reproduction needs to be on another platform like GitLab or Bitbucket because it's related to functionality only on that platform, then that's okay. +Please put your reproduction in a public repository on GitHub.com, if possible. + +You may put the reproduction on another platform like GitLab or Bitbucket, _if_ the reproduction needs features/behavior of that platform. ## Creating a minimal reproduction There are two ways to create a minimal reproduction: -- Start with an empty repository and copy files from your production repository -- Start with a fork of your production repository and remove files and config +- Start with an empty repository and _copy_ files from your production repository +- Start with a fork of your production repository and _remove_ files and config General steps: -1. Create your minimal reproduction repository on GitHub, only use GitLab or Bitbucket if needed +1. Put your minimal reproduction repository on GitHub, only use GitLab or Bitbucket if needed 1. Use the fewest number of repository files and dependencies -1. Reduce the Renovate config to a minimum +1. Reduce your Renovate config to a minimum 1. Remove private or secret information 1. Create a `readme.md` file that explains the current behavior and expected behavior 1. Set the repository visibility to `public` @@ -66,26 +72,27 @@ A production repository usually has: - many custom rules in the Renovate configuration file - many files that are not relevant -Having lots of "moving parts" makes debugging tricky, because debug break points can be triggered hundreds of times. +Having lots of "moving parts" makes it hard to debug, as debug break points can trigger hundreds of times. -When you have lots of custom config for Renovate, it's hard to find the root cause of the behavior. +When you have lots of custom config for Renovate, it's hard for us to find the root cause of the behavior. Bugs are often caused by multiple features interacting. -Reducing the config to a minimum helps us find out exactly which config elements are required to trigger the bug. +Reducing the config to a minimum helps us find exactly which config elements are needed to trigger the bug. ### "It's too much work to create a minimal reproduction" -If you don't create a minimal reproduction, the Renovate maintainers won't prioritize working on your issue. +If you do not create a minimal reproduction, the Renovate maintainers will not prioritize working on your issue. Discussions without a reproduction will probably go stale unless you, or somebody else, creates a minimal reproduction. ### "I already described what you need in the issue" Thank you for describing your issue in detail. -But we still need a minimal reproduction in a repository, and we'd like you to be the one to make sure it matches both your description as well as expected behavior. +But we still need a minimal reproduction in a repository. +We'd like you to make sure it matches both your description as well as expected behavior. ### Forcing Renovate to create a lot of pending updates Put an old version of a frequently updated dependency in your repository. -Set a high `minimumReleaseAge` for that dependency, for example: +Then set a high `minimumReleaseAge` for that dependency, for example: ```json {