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 debug tooling babel plugins. #133

Merged
merged 1 commit into from Apr 28, 2017

Conversation

Projects
None yet
4 participants
@rwjblue
Copy link
Member

rwjblue commented Apr 22, 2017

Implements ember-cli/rfcs#50 and the @ember/debug portion of emberjs/rfcs#176.

Below is the documentation being added to the README explaining the feature.


Debug Tooling

In order to allow addons to easily provide good development mode ergonomics (assertions, deprecations, etc) but still perform well in production mode ember-cli-babel automatically manages stripping / removing certain debug statements. This concept was originally proposed in ember-cli/rfcs#50, but has been slightly modified during implementation (after researching what works well and what does not).

Debug Macros

To add convienient deprecations and assertions, consumers (apps and/or addons) can do the following:

import { deprecate, assert } from '@ember/debug';

export default Ember.Component.extend({
  init() {
    this._super(...arguments);
    deprecate(
      'Passing a string value or the `sauce` parameter is deprecated, please pass an instance of Sauce instead',
      false,
      { until: '1.0.0', id: 'some-addon-sauce' }
    );
    assert('You must provide sauce for x-awesome.', this.sauce);
  }
})

In testing and development environments those statements will be executed (and assert or deprecate as appropriate), but
in production builds they will be inert (and stripped during minification).

General Purpose Env Flags

In some cases you may have the need to do things in debug builds that isn't related to asserts/deprecations/etc. For
example, you may expose certain API's for debugging only. You can do that via the DEBUG environment flag:

import { DEBUG } from '@glimmer/env';

const Component = Ember.Component.extend();

if (DEBUG) {
  Component.reopen({
    specialMethodForDebugging() {
      // do things ;)
    }
  });
}

In testing and development environments DEBUG will be replaced by the boolean literal true, and in production builds it will be replaced by false. When ran through a minifier (with dead code elimination) the entire section will be stripped.

Disabling Debug Tooling Support

If for some reason you need to disable this debug tooling, you can opt-out via configuration.

In an app that would look like:

// ember-cli-build.js
module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-babel': {
      disableDebugTooling: true
    }
  });

  return app.toTree();
}

In an addon that would look like:

// index.js

// ...snip...
init() {
  this._super.init.apply(this, arguments);

  this.options['ember-cli-babel'] = this.options['ember-cli-babel'] || {};
  this.options['ember-cli-babel'].disableDebugTooling = true;
}
// ...snip...

@rwjblue rwjblue force-pushed the rwjblue:add-stripping branch from 94ce290 to 33d656c Apr 22, 2017

@cibernox
Copy link
Contributor

cibernox left a comment

LGTM

@stefanpenner
Copy link
Member

stefanpenner left a comment

This looks awesome (but i did leave some nit-picks)

README.md Outdated
@@ -95,6 +95,92 @@ treeForAddon(tree) {
}
```

### Debug Tooling

In order to allow addons to easily provide good development mode ergonomics (assertions, deprecations, etc) but

This comment has been minimized.

@stefanpenner

stefanpenner Apr 24, 2017

Member

addons and apps?

README.md Outdated
// ...snip...
init() {
this._super.init.apply(this, arguments);

This comment has been minimized.

@stefanpenner

stefanpenner Apr 24, 2017

Member

Is it worth documenting how an addon would do this? This seems quite off the beaten path

@rwjblue rwjblue force-pushed the rwjblue:add-stripping branch from 33d656c to 665ef6d Apr 27, 2017

@rwjblue

This comment has been minimized.

Copy link
Member Author

rwjblue commented Apr 27, 2017

Pushed an update for the two README tweaks that @stefanpenner mentioned...

@rwjblue rwjblue force-pushed the rwjblue:add-stripping branch from 665ef6d to bf1c6b5 Apr 27, 2017


#### Debug Macros

To add convienient deprecations and assertions, consumers (in either an app or an addon) can do the following:

This comment has been minimized.

@stefanpenner

stefanpenner Apr 27, 2017

Member

can you add a bulleted list of available macros, or a link to where they are documented?

This comment has been minimized.

@rwjblue

rwjblue Apr 27, 2017

Author Member

Good point, updated!

@rwjblue rwjblue force-pushed the rwjblue:add-stripping branch from bf1c6b5 to a4c476d Apr 27, 2017

@stefanpenner

This comment has been minimized.

Copy link
Member

stefanpenner commented Apr 28, 2017

:shipit:

@rwjblue rwjblue merged commit cf36136 into babel:master Apr 28, 2017

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@rwjblue rwjblue deleted the rwjblue:add-stripping branch Apr 28, 2017

@Turbo87

This comment has been minimized.

Copy link
Contributor

Turbo87 commented on README.md in a4c476d Apr 28, 2017

@rwjblue shouldn't this be @ember/env?

This comment has been minimized.

Copy link
Member Author

rwjblue replied Apr 28, 2017

Nope

This comment has been minimized.

Copy link
Contributor

Turbo87 replied Apr 28, 2017

that seems very confusing given that the above helpers are imported from @ember/debug instead of @glimmer/debug...

This comment has been minimized.

Copy link
Contributor

Turbo87 replied Apr 28, 2017

also what about runInDebug?

This comment has been minimized.

Copy link
Member Author

rwjblue replied Apr 28, 2017

I'll add a brief explanation RE: @glimmer/env to the README shortly.

RE: runInDebug, it is not forgotten, you would just use if (DEBUG) like in the example below. I can try to explain that better in the README also.

@Turbo87 Turbo87 added the enhancement label Oct 27, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment