From 7cc403d5c8787c519348cce4569abc7e312fee94 Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 01:24:11 +0100 Subject: [PATCH 1/7] Add Debugging guidelines [skip ci] --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9387f43d..d6f8fb542 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,31 @@ To run current plugin timing on a file: $ ./scripts/plugin-timing.js file.js ``` +### Debugging + +When you use babili in your project and you find that there is a bug that appeared ONLY when you used babili, it's most likely that there is a bug in Babili and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. + +1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. +2. Try to predict the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination, simplify. +3. Every plugin that babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) +4. Once you suspect a few of the transformations that you think likely caused that bug, try toggling that from the preset. As a good practice, if you think it's NOT a mangler bug, turn OFF mangling and you should see the unmangled variable names to debug easier. +5. Sometimes it is NOT might not be a bug with ONLY one plugin, but the combinations of transformations. Again, deadcode and simplify are the major ones. You can start suspecting them first. +6. Sometimes it might because of the [unsafe transformations](packages/babel-preset-babili#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. +7. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. +8. [Report it 🙂](https://github.com/babel/babili/issues/new) +9. You're awesome. Thanks! + +#### Mangler bugs + +This should be the easy one. If there is an error thrown in your code which you can see it in the console, + +1. Just open the devtools and look at the variable that's mismatched (Usually it is the one that's in the Error message. If you have try..catch, add breakpoints in the try block and get the variable name that's faulty). +2. In current babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE. So it should be pretty easy to find that one declaration in your code. +3. Now, it boils down to finding that variable(or variables) which caused this error. +4. Usually, the containing function mapped to your original source code should help you reproduce the same error. +5. [Report it 🙂](https://github.com/babel/babili/issues/new) +6. You're awesome. Thanks! + ### Releasing > If you are releasing a new package, you'll want to run `./scripts/npm-owner-update.sh` to add all owners to the new npm package after releasing. Or do it manually via `https://www.npmjs.com/package/package-name-here/access`. From 60fd448c777bcc6a776721b4e2b666dbd542dc61 Mon Sep 17 00:00:00 2001 From: Henry Zhu Date: Mon, 20 Feb 2017 19:35:52 -0500 Subject: [PATCH 2/7] syntax errors [skip ci] --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6f8fb542..140984cba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,6 +68,16 @@ When you use babili in your project and you find that there is a bug that appear 8. [Report it 🙂](https://github.com/babel/babili/issues/new) 9. You're awesome. Thanks! +#### Syntax Errors + +If you get a syntax error at compile time, then it could be a few things: + +1. The parser itself doesn't handle the syntax being used (a [babylon](https://github.com/babel/babylon) bug). +2. The code is actually invalid syntax. +3. You didn't turn on the relevant Babel plugin for that syntax (if experimental). + +If the syntax error is at run time, then it means the outputted code is incorrect and and is a bug in the code generator, [babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator). + #### Mangler bugs This should be the easy one. If there is an error thrown in your code which you can see it in the console, From 109381fd8fe3198651fe69dc452b2e51f6d92391 Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 01:40:01 +0100 Subject: [PATCH 3/7] Update guidelines [skip ci] --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 140984cba..9bf32fa39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,13 +56,13 @@ $ ./scripts/plugin-timing.js file.js ### Debugging -When you use babili in your project and you find that there is a bug that appeared ONLY when you used babili, it's most likely that there is a bug in Babili and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. +In your project, if you find that there is a bug that appears ONLY when you use Babili, it's most likely that there is a bug in Babili and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. 1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. -2. Try to predict the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination, simplify. -3. Every plugin that babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) +2. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. +3. Every plugin that Babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) 4. Once you suspect a few of the transformations that you think likely caused that bug, try toggling that from the preset. As a good practice, if you think it's NOT a mangler bug, turn OFF mangling and you should see the unmangled variable names to debug easier. -5. Sometimes it is NOT might not be a bug with ONLY one plugin, but the combinations of transformations. Again, deadcode and simplify are the major ones. You can start suspecting them first. +5. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, deadcode and simplify are the major ones. You can start suspecting them first. 6. Sometimes it might because of the [unsafe transformations](packages/babel-preset-babili#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. 7. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. 8. [Report it 🙂](https://github.com/babel/babili/issues/new) @@ -83,7 +83,7 @@ If the syntax error is at run time, then it means the outputted code is incorrec This should be the easy one. If there is an error thrown in your code which you can see it in the console, 1. Just open the devtools and look at the variable that's mismatched (Usually it is the one that's in the Error message. If you have try..catch, add breakpoints in the try block and get the variable name that's faulty). -2. In current babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE. So it should be pretty easy to find that one declaration in your code. +2. In current Babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE. So it should be pretty easy to find that one declaration in your code. 3. Now, it boils down to finding that variable(or variables) which caused this error. 4. Usually, the containing function mapped to your original source code should help you reproduce the same error. 5. [Report it 🙂](https://github.com/babel/babili/issues/new) From f9585e0f506ba605e8c4b88e2bb891b6340e8284 Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 02:09:34 +0100 Subject: [PATCH 4/7] Reorder [skip ci] --- CONTRIBUTING.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bf32fa39..47ed677c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,6 +58,20 @@ $ ./scripts/plugin-timing.js file.js In your project, if you find that there is a bug that appears ONLY when you use Babili, it's most likely that there is a bug in Babili and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. +#### Compile time Errors + +If you get a syntax error at compile time, then it could be a few things: + +1. The parser itself doesn't handle the syntax being used (a [babylon](https://github.com/babel/babylon) bug). +2. The code is actually invalid syntax. +3. You didn't turn on the relevant Babel plugin for that syntax (if experimental). + +If the syntax error is at run time, then it means the outputted code is incorrect and and is a bug in the code generator, [babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator). + +#### Runtime errors + +When you run your minified code in the browser, + 1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. 2. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. 3. Every plugin that Babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) @@ -68,17 +82,7 @@ In your project, if you find that there is a bug that appears ONLY when you use 8. [Report it 🙂](https://github.com/babel/babili/issues/new) 9. You're awesome. Thanks! -#### Syntax Errors - -If you get a syntax error at compile time, then it could be a few things: - -1. The parser itself doesn't handle the syntax being used (a [babylon](https://github.com/babel/babylon) bug). -2. The code is actually invalid syntax. -3. You didn't turn on the relevant Babel plugin for that syntax (if experimental). - -If the syntax error is at run time, then it means the outputted code is incorrect and and is a bug in the code generator, [babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator). - -#### Mangler bugs +##### Mangler bugs This should be the easy one. If there is an error thrown in your code which you can see it in the console, From db2a8128b62aa70701f3600af277deecbd397bde Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 02:18:04 +0100 Subject: [PATCH 5/7] shorten [skip ci] --- CONTRIBUTING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47ed677c0..70b151479 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ When you run your minified code in the browser, 1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. 2. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. 3. Every plugin that Babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) -4. Once you suspect a few of the transformations that you think likely caused that bug, try toggling that from the preset. As a good practice, if you think it's NOT a mangler bug, turn OFF mangling and you should see the unmangled variable names to debug easier. +4. Once you suspect a few transformations, try toggling that from the preset. As a good practice, if you think it's NOT a mangler bug, turn OFF mangling and you should see the unmangled variable names to debug easier. 5. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, deadcode and simplify are the major ones. You can start suspecting them first. 6. Sometimes it might because of the [unsafe transformations](packages/babel-preset-babili#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. 7. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. @@ -84,14 +84,13 @@ When you run your minified code in the browser, ##### Mangler bugs -This should be the easy one. If there is an error thrown in your code which you can see it in the console, +This should be the easy one. If there is an error thrown in the console, 1. Just open the devtools and look at the variable that's mismatched (Usually it is the one that's in the Error message. If you have try..catch, add breakpoints in the try block and get the variable name that's faulty). -2. In current Babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE. So it should be pretty easy to find that one declaration in your code. -3. Now, it boils down to finding that variable(or variables) which caused this error. -4. Usually, the containing function mapped to your original source code should help you reproduce the same error. -5. [Report it 🙂](https://github.com/babel/babili/issues/new) -6. You're awesome. Thanks! +2. In current Babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE (except `var`s which can be declared mutiple times, but all those will still be in one function block). So it should be pretty easy to find that one declaration in your code. +3. Usually, the containing function should help you reproduce the same error. +4. [Report it 🙂](https://github.com/babel/babili/issues/new) +5. You're awesome. Thanks! ### Releasing From 4f007948afdbb09c54186cf292a2972185bab687 Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 02:20:13 +0100 Subject: [PATCH 6/7] update [skip ci] --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70b151479..15960f581 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,7 +86,7 @@ When you run your minified code in the browser, This should be the easy one. If there is an error thrown in the console, -1. Just open the devtools and look at the variable that's mismatched (Usually it is the one that's in the Error message. If you have try..catch, add breakpoints in the try block and get the variable name that's faulty). +1. In the devtools find the variable that's mismatched (Usually it is the one that's in the Error message. If you have try..catch, add breakpoints in the try block and get the variable name that's faulty). 2. In current Babili, there is no variable reuse (Fix in [#284](https://github.com/babel/babili/pull/284)). So, every variable that you see is declared ONLY ONCE (except `var`s which can be declared mutiple times, but all those will still be in one function block). So it should be pretty easy to find that one declaration in your code. 3. Usually, the containing function should help you reproduce the same error. 4. [Report it 🙂](https://github.com/babel/babili/issues/new) From 9c641edc73f4e3a3e8654d15bbf72fd0ebfdcdec Mon Sep 17 00:00:00 2001 From: Boopathi Rajaa Date: Tue, 21 Feb 2017 18:27:22 +0100 Subject: [PATCH 7/7] Update [skip ci] --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 15960f581..a6e324dfd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,7 +66,7 @@ If you get a syntax error at compile time, then it could be a few things: 2. The code is actually invalid syntax. 3. You didn't turn on the relevant Babel plugin for that syntax (if experimental). -If the syntax error is at run time, then it means the outputted code is incorrect and and is a bug in the code generator, [babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator). +If the syntax error occurs at runtime, it likely means the code generator ([babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator)) has a bug and has output invalid code. #### Runtime errors @@ -75,8 +75,8 @@ When you run your minified code in the browser, 1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. 2. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. 3. Every plugin that Babili uses has an option in preset to toggle it on/off - [preset-options](packages/babel-preset-babili#options) -4. Once you suspect a few transformations, try toggling that from the preset. As a good practice, if you think it's NOT a mangler bug, turn OFF mangling and you should see the unmangled variable names to debug easier. -5. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, deadcode and simplify are the major ones. You can start suspecting them first. +4. Disable any transformation(s) that you suspect are causing problems. Turning OFF mangling (`mangle: false`) is a good practice if you don't think it's related to a mangling bug, since unmangled variable names will make debugging easier. +5. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, `deadcode-elimination` and `simplify` maybe good candidates to start with here as they perform many transformations. 6. Sometimes it might because of the [unsafe transformations](packages/babel-preset-babili#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. 7. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. 8. [Report it 🙂](https://github.com/babel/babili/issues/new)