renovate/renovate
1
0
Fork 0
mirror of https://github.com/renovatebot/renovate.git synced 2025-01-11 22:46:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs: improve minimal reproductions guide (#28926)

Browse source
This commit is contained in:
HonkingGoose 2024-05-08 12:37:21 +02:00 committed by GitHub
parent 97926c06e9
commit 596d743cf7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 28 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
docs/development/minimal-reproductions.md
View file

@ -2,7 +2,11 @@
We may ask you to create a "minimal reproduction" repository to help us fix bugs or work on a feature. 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 ## 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 ## 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. A reproduction confirms the problem is with Renovate, and _not_ with your environment, or your configuration settings.
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 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. When a reproduction has minimal config, we can oftern narrow down, or identify the root cause.
This means we can often help you from code inspection alone. 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. Finally, with minimal code and dependencies, we can step through with a debugger.
Production repositories or non-minimal reproductions are often very difficult to debug because break points get triggered dozens or hundreds or times. 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? ## 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 should have 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.
## Where to host the minimal reproduction ## Where to host the minimal reproduction
Unless it's impossible, use a public repository on GitHub.com to host your reproduction. Please put your reproduction in a public repository on GitHub.com, if possible.
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.
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 ## Creating a minimal reproduction
There are two ways to create 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 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 a fork of your production repository and _remove_ files and config
General steps: 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. 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. Remove private or secret information
1. Create a `readme.md` file that explains the current behavior and expected behavior 1. Create a `readme.md` file that explains the current behavior and expected behavior
1. Set the repository visibility to `public` 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 custom rules in the Renovate configuration file
- many files that are not relevant - 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. 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" ### "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. 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" ### "I already described what you need in the issue"
Thank you for describing your issue in detail. 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 ### Forcing Renovate to create a lot of pending updates
Put an old version of a frequently updated dependency in your repository. 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 ```json
{ {