|
| 1 | +Creating a Bug Reproducer |
| 2 | +========================= |
| 3 | + |
| 4 | +The main Symfony code repository receives thousands of issues reports per year. |
| 5 | +Some of those issues are so obvious or easy to understand, that Symfony Core |
| 6 | +developers can fix them without any other information. However, other issues are |
| 7 | +much harder to understand because developers can't easily reproduce them in their |
| 8 | +computers. That's when we'll ask you to create a "bug reproducer", which is the |
| 9 | +minimum amount of code needed to make the bug appear when executed. |
| 10 | + |
| 11 | +Reproducing Simple Bugs |
| 12 | +----------------------- |
| 13 | + |
| 14 | +If you are reporting a bug related to some Symfony component used outside the |
| 15 | +Symfony framework, it's enough to share a small PHP script that when executed |
| 16 | +shows the bug:: |
| 17 | + |
| 18 | + // First, run "composer require symfony/validator" |
| 19 | + // Then, execute this file: |
| 20 | + <?php |
| 21 | + require_once __DIR__.'/vendor/autoload.php'; |
| 22 | + use Symfony\Component\Validator\Constraints; |
| 23 | + |
| 24 | + $wrongUrl = 'http://example.com/exploit.html?<script>alert(1);</script>'; |
| 25 | + $urlValidator = new Constraints\UrlValidator(); |
| 26 | + $urlConstraint = new Constraints\Url(); |
| 27 | + |
| 28 | + // The URL is wrong, so var_dump() should display an error, but it displays |
| 29 | + // "null" instead because there is no context to build a validator violation |
| 30 | + var_dump($urlValidator->validate($wrongUrl, $urlConstraint)); |
| 31 | + |
| 32 | +Reproducing Complex Bugs |
| 33 | +------------------------ |
| 34 | + |
| 35 | +If the bug is related to the Symfony Framework or if it's too complex to create |
| 36 | +a PHP script, it's better to reproduce the bug by forking the Symfony Standard |
| 37 | +edition. To do so: |
| 38 | + |
| 39 | +1. Go to https://github.com/symfony/symfony-standard and click on the **Fork** |
| 40 | + button to make a fork of that repository or go to your already forked copy. |
| 41 | +2. Clone the forked repository into your computer: |
| 42 | + ``git clone git://github.com/YOUR-GITHUB-USERNAME/symfony-standard.git`` |
| 43 | +3. Browse the project and create a new branch (e.g. ``issue_23567``, |
| 44 | + ``reproduce_23657``, etc.) |
| 45 | +4. Now you must add the minimum amount of code to reproduce the bug. This is the |
| 46 | + trickiest part and it's explained a bit more later. |
| 47 | +5. Add, commit and push all your changes. |
| 48 | +6. Add a comment in your original issue report to share the URL of your forked |
| 49 | + project (e.g. ``https://github.com/YOUR-GITHUB-USERNAME/symfony-standard/tree/issue_23567``) |
| 50 | + and, if necessary, explain the steps to reproduce (e.g. "browse this URL", |
| 51 | + "fill in this data in the form and submit it", etc.) |
| 52 | + |
| 53 | +Adding the Minimum Amount of Code Possible |
| 54 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 55 | + |
| 56 | +The key to create a bug reproducer is to solely focus on the feature that you |
| 57 | +suspect is failing. For example, imagine that you suspect that the bug is related |
| 58 | +to a route definition. Then, after forking the Symfony Standard Edition: |
| 59 | + |
| 60 | +1. Don't edit any of the default Symfony configuration options. |
| 61 | +2. Don't copy your original application code and don't use the same structure |
| 62 | + of bundles, controllers, actions, etc. as in your original application. |
| 63 | +3. Open the default controller class of the AppBundle and add your routing |
| 64 | + definition using annotations. |
| 65 | +4. Don't create or modify any other file. |
| 66 | +5. Execute the ``server:run`` command and browse the previously defined route |
| 67 | + to see if the bug appears or not. |
| 68 | +6. If you can see the bug, you're done and you can already share the code with us. |
| 69 | +7. If you can't see the bug, you must keep making small changes. For example, if |
| 70 | + your original route was defined using XML, forget about the previous route |
| 71 | + annotation and define the route using XML instead. Or maybe your application |
| 72 | + uses bundle inheritance and that's where the real bug is. Then, forget about |
| 73 | + AppBundle and quickly generate a new AppParentBundle, make AppBundle inherit |
| 74 | + from it and test if the route is working. |
| 75 | + |
| 76 | +In short, the idea is to keep adding small and incremental changes to the default |
| 77 | +Symfony Standard edition until you can reproduce the bug. |
0 commit comments