search

zambezi / ez-build

Zambezi build tool
MIT License
2 stars 1 forks source link

Deprecate babelrc #43

Closed mstade closed 7 years ago

mstade commented 8 years ago

Description

In #36 we discuss the idea of removing .babelrc support altogether, and instead support a fixed number of customizations by way of compiler flags. The proposal is:

The order in which flags are specified does not matter. For example these should all be equivalent:

ez-build --flags es2017,es-stage:0
ez-build --flags es-stage:0,es2017
ez-build --flags es-stage:0 --flags es2017
ez-build --flags es2017 --flags es-stage:0

Motivation and Context

By enabling the loading of .babelrc, we introduce a leak in the abstraction: users should not need to know ez-build internals in order to use or customize it. At the same time, the amount of flexibility afforded by this exposure is limited, due to how the options that ez-build sets internally are merged with those specified in the .babelrc file. This is confusing, and downright limiting in other cases.

We've observed that most ez-build use cases just add the React preset, sometimes with additional ES stages to include functionality intended for an upcoming version of the spec. This suggests we can cover a large range of "typical" cases with little added overhead (arguably less than before) and extend ez-build further should the need arise in the future.

How Was This Tested?

Both unit and CLI tests added.

Types of changes

mstade commented 8 years ago

Additionally, we should expand the rationale with a checklist for what features make sense to include with ez-build. In #36 i proposed the following, but I think it needs some further thought:

Feature checklist

If one or more of these questions have an affirmative answer, the feature is potentially a good candidate for ez-build.

  • [ ] Is the feature part of a ratified standard, such as ECMAScript or a W3C spec?
  • [ ] Is the feature on track to become part of a ratified standard, such as ECMAScript or a W3C spec?
  • [ ] Is the feature widely used in the developer community? (How would we measure this? Code search on GitHub?)
  • [ ] Is the feature reasonably stable; are there frequent breaking changes?
  • [ ] Is the feature backed by any organizations, commercial, non-profit, or otherwise?
  • [ ] Is the feature actively developed or supported?
  • [ ] Is the feature in line with the goals of ez-build, as described in the rationale?
codecov-io commented 8 years ago

Current coverage is 93.81% (diff: 100%)

Merging #43 into master will increase coverage by 6.12%

@@             master        #43   diff @@
==========================================
  Files            15         15          
  Lines           268        307    +39   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits            235        288    +53   
+ Misses           33         19    -14   
  Partials          0          0

Powered by Codecov. Last update 8fe03b7...90c202e

grancalavera commented 8 years ago

for stage 4 proposals (we already started doing this with #35, just saying we should do it yearly, so when es2017 is ratified it gets enabled by default, and the flag changes to --flags es2018 instead

Wouldn't it make more sense to create a flag like node's --harmony and document the semantics just like you did above? Something like "stage-4 proposal to be ratified for the next standard".

I would just make sure it does not include the word "stage" in it. Maybe --esnext, not sure.

mstade commented 8 years ago

Wouldn't it make more sense to create a flag like node's --harmony and document the semantics just like you did above? Something like "stage-4 proposal to be ratified for the next standard".

I would just make sure it does not include the word "stage" in it. Maybe --esnext, not sure.

I did consider that, but the problem with that is the same as with stages: the semantics change over time. Stage 0 today will not be the same as stage 0 a year from now, but es2016 will – it's ratified and set in stone. If we have something like --esnext then any project which happened to use this in 2016, and having es2017 in mind as the next version, could see different results down the line as we get to es2018 and beyond. Hopefully future versions of the standard are non-breaking, but history tells us that's probably not going to be true. So it's about the ability to reason about the future, all the while having the safety of allowing you to "forget" you had a flag in the project and accidentally leaving it behind, yet still having the build work as expected. As we deprecate "the next" flags as standards get ratified, they will simply become safe no-ops. (Although, this suggests we should allow disabling versions, thus allowing you to "go back in time" since otherwise the default behavior is to use whatever the latest ratified spec is..)

grancalavera commented 8 years ago

I just think maintaining the --es[year] flags will be a burden, but the only alternative I can think if is relying on semver to make sure that at any given minor version --esnext (or whatever) behaves as documented. For instance, we can document --esnext refers to the ratified standard for 2016... but as you can see is just moving the maintenance issue elsewhere and at the same time making it more opaque.

DimitarChristoff commented 8 years ago

I don't like the idea of the change and still believe it's the wrong thing to do. you are undertaking to keep abstractions for every type of plugin/transform etc that babel can support. that's not agile, it's cumbersome and a big undertaking that won't bring any clear benefit to anybody other than to draw a border that says 'we support only this' - it's self-serving

grancalavera commented 8 years ago

I think ez-build should have the minimum possible set of configuration options, and such options must come from some rationale based on an authoritative source, e.g. the TC39 list of proposals.

In that sense I like @mstade proposal to remove .babelrc and instead concisely describe what ez-build actually does through the API.

Any feature that is not achievable with such small set of configuration options should fall out of the scope of ez-build, and projects wanting to use those features should choose another building tool.

DimitarChristoff commented 8 years ago

isn't the point to ez-build to get people to buy into it - if we can support something, we should not disallow it. if people choose a different tool because we are choosing to dumb down options on purpose, we are limiting the scope and usefulness of the tool.

Poetro commented 8 years ago

If we remove the .babelrc file, the user is still responsible to install the stage-0 plugin, etc, that would be required by the --flags? If it is so, what are we hiding?

DimitarChristoff commented 8 years ago

@Poetro i think it came down to order of plugins cannot be guaranteed -- stage-0 needs to be last or it does not work.

so if babelrc has plugins defined that use ['react', 'es2015', 'stage-0'] and ez-build does append to that array, it breaks. it's either one or the other source, or a smart merge with knowledge, which makes it difficult.

mstade commented 8 years ago

If we remove the .babelrc file, the user is still responsible to install the stage-0 plugin, etc, that would be required by the --flags? If it is so, what are we hiding?

I'll comment on other things in this thread as well, but wanted to quickly address this. No, the user wouldn't have to install any presets or plugins, ez-build would come batteries included. The proposed --flags es-stage-{0,1,2,3} has just not been added in this PR yet, it's still very much work in progress. For all intents and purposes, the user wouldn't even know what compiler(s) are used internally. (Unless they looked, obviously.)

Poetro commented 8 years ago

@mstade thanks for that information, it now makes much more sense.

mstade commented 8 years ago

I just think maintaining the --es[year] flags will be a burden. [...] For instance, we can document --esnext refers to the ratified standard for 2016... but as you can see is just moving the maintenance issue elsewhere and at the same time making it more opaque. – @grancalavera

This is exactly my line of thinking. We can do it this way, but the semantics are slightly different and we'd just be moving the maintenance burden around – not removing it. The semantic difference is one of being explicit over being implicit; --flags es2018 explicitly says "opt in to es2018" but --flags esnext says "opt in to whatever happens to come next." In a way, since we'll be defaulting ratified specs to be enabled over time, this is already true, it's just a matter of when that happens. I.e. does it happen immediately as these specs become available, including changes to them, or does it happen on a case-by-case basis until they are ratified and thus available to all? An esnext flag would mean "all future versions" whereas something like es2018 explicitly means ecmascript 2018 and nothing else. Once that spec is ratified and available to all, the flag becomes a no-op. An esnext flag would never become a no-op. (Not technically true, there is possibly a vacuum between es versions before features move to stage 4, but you know what I mean.)

Regardless, we'd have to keep up the maintenance on the included presets and plugins anyway and the flag maintenance is practically negligible.

mstade commented 8 years ago

isn't the point to ez-build to get people to buy into it - if we can support something, we should not disallow it. if people choose a different tool because we are choosing to dumb down options on purpose, we are limiting the scope and usefulness of the tool. – @DimitarChristoff

Limiting scope is the purpose entirely. When there's a mountain of options, an endless amount of flexibility, you can do anything but get help with nothing. The point of ez-build is to build conventional web projects; to cover the 80% use case and let other solutions solve (or not, as it may be) the remaining 20%. It's about making it easy to build typical projects, and let others take care of the esoteric ones.

FabienDeshayes commented 8 years ago

The point of ez-build is to build conventional web projects; to cover the 80% use case and let other solutions solve (or not) the remaining 20%.

I'm in line with that and I think it should be made clearer if it's not already.

mstade commented 8 years ago

@Poetro i think it came down to order of plugins cannot be guaranteed -- stage-0 needs to be last or it does not work. – @DimitarChristoff

It's a bit more than that, but it's an important reason for sure. Essentially it comes down this:

We could solve the first issue by embedding know-how, and keeping tabs on what's compatible with what, trying to stay ahead of the curve. This is hard, and maintenance heavy, but not impossible.

The second issue is arguably more important to resolve – at least I think so. If we spill the guts of ez-build on to the user, we're not only adding more cognitive overhead for them, we're also shooting ourselves in the foot in terms of our ability to actually change those guts. It's much, much harder to change up your internals when they are exposed in your interface. The mechanics, as it were, aren't as important as the facade.

mstade commented 8 years ago

Here's what an example deprecation notice looks like this:

$ ez-build
WARNING: ez-build is discontinuing support for .babelrc 

Currently ez-build still loads .babelrc files, but this support is
going away before v1.0.0. Please make sure to migrate any relevant
configuration to use flags instead.

Not sure how to migrate? Please open an issue:

https://github.com/zambezi/ez-build/issues/new

Comments on the detected babel configuration:

- To enable react support, use: --flags react
- To enable amd modules, use: --flags modules:amd
- babel.env: NODE_ENV is respected by ez-build