Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Debugging guidelines [skip ci] #437

Merged
merged 7 commits into from Feb 21, 2017
Merged

Add Debugging guidelines [skip ci] #437

merged 7 commits into from Feb 21, 2017

Conversation

boopathi
Copy link
Member

@boopathi boopathi commented Feb 21, 2017

CONTRIBUTING.md Outdated
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consistent caps of Babili unless it's in quotes: babili?

CONTRIBUTING.md Outdated
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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the syntax error occurs at runtime, it likely means the code generator (babel-generator) has a bug and has output invalid code.

CONTRIBUTING.md Outdated
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, deadcode-elimination and simplify may be good candidates to start with here as they perform many transformations.

CONTRIBUTING.md Outdated
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe:

Disable any transformation(s) that you suspect are causing problems. Turning OFF mangling is a good practice if you don't think it's related to a mangling bug, since unmangled variable names will make debugging easier.

@boopathi
Copy link
Member Author

boopathi commented Feb 21, 2017

@existentialism 👍

@hzoo hzoo added the Tag: Docs Pull Request updating Documentation label Feb 21, 2017
@boopathi boopathi merged commit b51b2c4 into master Feb 21, 2017
@boopathi boopathi deleted the contrib-0 branch March 3, 2017 17:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Tag: Docs Pull Request updating Documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants