Document requirements for `carbon-charts` packages

[joshblack]

@shinytoyrobots had the suggestion to create an internal-only document of an audit of the current carbon-charts project. This audit should contain the following:

• High-level overview of the project and its purpose
• Summary of overall issues/defects with the project
• Suggestions for enhancements to make
• Suggestions for requirements for official public release
• Suggestions for roadmaps for packages, including styles, react, angular, vanilla

[joshblack]

cc @tw15egan

[shinytoyrobots]

I'd like to get a comprehensive document.

But also a "diplomatic" document. Which can really be a clear reasoning for why carbon-charts should not be in the IBM org (so we can at least drag it into carbon-design-system). e.g.- security warnings, lack of ability to pull down and replicate.

Ideally would like to have that piece so that we can move the repo by the end of this sprint (either me or @alisonjoseph to connect with Dean Williams first to explain).

[shinytoyrobots]

Probably should do this reasonably quickly, as got a voicemail from Dean about hearing about this, and curious as to the justification.

I also think we could reasonably argue that core component repos are the only ones we want to put in /IBM org at this point.

@kuehndaniel - could you also weigh in here on some of the broader ideas for data viz solutions - with Accurat, etc?

[tw15egan]

The only ones that are under IBM are repos that have been approved by the Core Carbon team and adhere to a specific guideline. This one was not approved by the Core Carbon team, and thus should be moved under the Carbon Design System umbrella, like the current Data Viz repo, until it is approved. This is my understanding

[shinytoyrobots]

We (I...) made the mistake when they came down for the workshop of accepting the idea of IBM/carbon-charts as something that we could use their solution for. So it's as much a diplomatic problem as an actual practical one.

Your response is absolutely right, we just need to have those guidelines a little clearer so that we can point out where it didn't adhere.

[joshblack]

Here's some high-level notes:

• On contribution for stable packages:
  • CONTRIBUTING.md should provide a way for anyone to pull down the codebase and work on it in order to submit a PR. One might run into trouble with the current repo because the guidance for running charts is out-of-date or does not work Reference
  • In addition, sections in CONTRIBUTING.md that call out things for Pull Requests (like npm run lint) will error out because dependencies are missing
  • The CONTRIBUTING.md documentation also suggests commit criteria that is not up-to-date after viewing the commit history in the repo: https://github.com/IBM/carbon-charts/blob/master/CONTRIBUTING.md#contribution-process, namely the usage of emojis
• On the README.md
  • It does not suggest that this package is experimental in any location
  • It implies that code is stable in the following location: https://github.com/IBM/carbon-charts#component-status
  • Neither of the links provided in this section for docs exist: https://github.com/IBM/carbon-charts#demo-and-documentation
• On code quality
  • Several test files are commented out: [1] [2]
• On 1.0 Release criteria
  • Each package should have proper README with documentation and guidance on how to use the package. For example: https://github.com/joshblack/carbon-charts/tree/master/packages/core should be more descriptive
  • There should be a dedicated style package that exposes the styling of data visualizations for any implementation, in addition to detailing how to use it
  • It should also follow the carbon style conventions
  • There is a React package that should not exist https://github.com/IBM/carbon-charts/tree/master/packages/react
  • Packages should not be bundled by webpack, and there should be greater attention devoted to proper bundling strategies and bringing the data viz work in with respect to performance (d3 is a large package)
  • The provided patterns do not match any design guidance we offer

TL;DR the experience of consuming the packages need to be improved in order to be considered stable. This includes improving docs for contributing, from how to fork the project to bringing it down, running locally, and ultimately creating a pull request. In addition, there should be a greater attention to performance for teams that are using these components, which would require a smarter bundling strategy that using webpack to build the dist folders that currently exist.

[shinytoyrobots]

Perfect. I can flag that - especially because we're not saying any of those flaws are inherently wrong, merely that they are tests against which something "core" needs to pass.

[kuehndaniel]

As far as specific data viz planning, we want to take the original design language guidance and visuals (https://www.ibm.com/design/language/experience/data-visualization/) and update them to the new language. In time we would either code those data viz modules or teams from around the business code them and contribute back. I was hoping the WCE charts would be a shorthand to getting the base set of charts coded, but it sounds like that's not an option currently if the code doesn't meet certain standards. Updating the current charts is not a priority right now, but if we have guidance to give WCE they are open to taking on that work. Diplomacy is important, too.