document migrating from istanbul to nyc configuration

[bcoe]

see #309

Open Questions

• should we support both the nyc and the istanbul configuration key in package.json (it's a bit confusing for folks using libraries like babel-plugin-istanbul that they need to set an nyc stanza).
  • I could see the other argument, whatever, nyc is the name of the actual reporting tool get used to it.
• do we need a tool for migration, or could we get away with documenting this on our website?

CC: @jamestalmage, @gotwarlost curious about your thoughts.

[novemberborn]

I could see the other argument, whatever, nyc is the name of the actual reporting tool get used to it.

That would definitely help communicate any breaking changes.

[dpogue]

Possibly outside the scope of this particular discussion, but a document outlining API changes would be helpful. I'm interested in getting karma-coverage ported to the new istanbul API to resolve some long-standing sourcemap issues.

[gotwarlost]

We are again in a place that is neither here nor there :) We now have low level libs like istanbul-lib-coverage, istanbul-lib-source-map etc. but nyc doesn't use the istanbul-api mid-level API.

For that reason, I'm reluctant to make istanbul-api a first-class citizen and just let people use the lower level libs. Docs for those are sorta-kinda present as JS doc but not yet published anywhere.

(still catching up on all my github emails so unsure if things have changed :) )

[gotwarlost]

Previous comment was in reply to @dpogue - now trying to address the main issue.

I think if nyc does not respect the istanbul config any more, we should just drop it replacing it with whatever nyc allows for configuration. We might need to add some knobs in nyc to support watermarks and other reporting config.

Now, the nyc stanza becomes the config for istanbul. We might want to read the babel plugin config from here if possible.

It would be nice if we could have a centralized config that everyone could use including nyc, babel-plugin-istanbul and, say, the karma coverage plugin.

Also, is it worthwhile not making the babel plugin a top-level thing in itself but packing it inside of nyc? I think it is possible to declare a babel plugin as a path inside a package.

The advantage I see with this approach is that it shows the relationships between the libraries clearly and packages common dependencies once. As it stands, since nyc bundles its dpendencies and the plugin doesn't, one ends up with multiple versions of dependencies (at least I think that is what could happen even if it doesn't now).

[jeffijoe]

I think we should definitely have a .nycrc - embedding the nyc config in the package.json feels wrong to me. It makes sense that e.g. babel-plugin-instanbul supports nyc options in the .babelrc, and they should take precedence over the values in .nycrc. Deep merge perhaps? Babel does it.

[ChrisPearce]

Having a .nycrc would be very helpful when transitioning from projects that already have a .istanbul.yml file.

From a version control perspective I think it is a lot easier to identify changes in a .nycrc file, rather than those changes getting lumped in with other changes to an unrelated package.json file.

Also, on more complex projects, the package.json can already get quite large and complicated.

[jeffijoe]

I could see the other argument, whatever, nyc is the name of the actual reporting tool get used to it.

According to nycs readme:

Istanbul's state of the art command line interface

So it's not just a reporting tool, unless I didn't understand that first line in the readme correctly. 😄

I hope we will see support for a .nycrc soon. Istanbul team, thanks for all your hard work!