[VZ] Overview

[contolini]

CFv2 will be a substantial restructuring tracked with the Voltrazord milestone. The goal of this release is speed. Using CF quickly, contributing to CF quickly, squashing CF bugs quickly.

Guiding Stories

As a CFPB front-end web developer,
I want to copy/paste CF HTML snippets,
So that I can quickly and confidently build UIs.

As a CFPB front-end web developer,
I want CF source code to live in one place,
So that contributing to the framework is straightforward.

Acceptance Criteria

• All CF source code exists in a single repo.
• All CF components are independently published to npm (i.e. a consumer can npm i cf-buttons).
• All open CF GH issues are part of this repo with the component name in brackets in the title.
• A GH issue label exists for every component and issues are labeled appropriately.
• All CF usage docs exist in a single location. See docs management strategy discussion. Contribution docs will be left in CONTRIBUTING.md in this repo.
• Transition to a proper git release flow.
• Make a decision on Bower (see known obstacle below), either:
  • Drop support and move to npm
  • Auto-push component updates to discrete component repos using a bot Not doing this.
  • Publish CF as a whole to Bower and don't separate components
• More ASCII art, preferably of animals and/or robots.

Known obstacles:

• Maintaining Bower support will be tricky. Bower, unlike npm, doesn't store package tarballs. This means every component needs its own repo. Some frameworks handle this through scripted pusher bots. Other frameworks simply don't support independent component installation via Bower. After following the discussion on LockFile Feature bower/bower#1748, wherein it is revealed that there is only one maintainer remaining on the Bower project, and its future hinges on the success of a patronage-based model, we decided to drop support for Bower.

See #168 for a history of what went into CFv1.

[contolini]

@cfpb/front-end-team-admin Concrete user stories came out of yesterday's discussions. Acceptance criteria is still emerging. Hit me up here or on chat with any questions/concerns.

[awolfe76]

This is great.

A couple thoughts:

1. Speed - the point of a framework is to help us implement solution quickly. When using the framework I find the opposite happening. I think moving everything under the one repo, moving to only npm (not sure what this does to other teams), and clean HTML snippets will help here.
2. The build - whatever build tool is used, grunt/gulp/scripts, simple is great. The fewer options, the better. If tasks can't be removed, something like load-grunt-config goes a long way toward making tasks more manageable.
3. Speed - yes, again. But this time for contributing. This ties pretty closely to 'the build', but just in general it should be really straightforward for us to make updates.
4. Docs - seems like there should be a way to integrate the design manual with the framework docs, so that both get generated at the same time (or are even the same?). Using npm it's easy to ignore docs for publishing but still have them available in Github, less clutter doing a npm install.
5. Variables - all in one place please.

@contolini mentions most of this already, just want to second it and mention some of my pain points.

[Scotchester]

Thanks for your thoughts, @awolfe76!

Speed - the point of a framework is to help us implement solution quickly. When using the framework I find the opposite happening.

What slows you down with the current stuff we have?

Variables - all in one place please.

If you use the generator, you get that in the form of our cf-vars-overrides.less file. Is there a more elegant way to handle this?

[awolfe76]

What slows you down with the current stuff we have?

To be honest, it was a while back and I would have to try to build something with it again to really try to give you details. Which I'll do to be more helpful.

But from what I do remember, it took me a while to wrap my head around everything that was happening in the build process (maybe that was me?) but I don't think that it should take time to do. Could be more apparent. I did need to make tweaks to the Grunt tasks for my project needs ... all related to my 2nd bullet.

Where to place overrides and have them included. I think you and I together eventually worked through this. 😄 But this seems like it shouldn't be required, at least very much, when working on a CFPB project.

I found it hard to discover what was possible. Maybe some cleaner documentation would help. Documentation seems like an ongoing pain point for most. Using bootstrap as an example, their docs are easy to navigate and easy to see exactly what you can do, and how to do it. But also, having built things with bootstrap in the past I don't think the documentation was always required. Something about the code base made it clear what you could do with it. Hard to say exactly what that was/is, but again, I'll try something with CF again to see.

If you use the generator, you get that in the form of our cf-vars-overrides.less file. Is there a more elegant way to handle this?

Having one repo, so only one file with variables, seems to do this better. May even remove the need for the generator? If it's one repo, you build and include the right files.

I tend to dig through Github to find things quite a bit (prior to use and even during) and tracking down where a variable was set proved difficult at times.

[contolini]

@awolfe76 I really like the theme of "speed" for this release. And I think you're right that having clear documentation in a single location will do wonders.

[KimberlyMunoz]

it took me a while to wrap my head around everything that was happening in the build process (maybe that was me?)

🙋🏽I've been working in CF since March and I still struggle to debug the build process. I keep forgetting about cf-grunt-config and it's not really clearly documented anywhere. Moving to one repo removes the need for that forgotten grunt repo. We have all our gulp tasks in one separated out folder and it's nice. 👌🏽

[Scotchester]

There's an interesting parallel discussion thing happening now. @awolfe76 is talking mostly about consuming the framework, but @KimberlyMunoz's point (and the driving force between all the "single repo" talk), is about making it easier for contributors to CF.

@awolfe76 On vars/overrides: This is where the generator shines. It provides you with a project ready to roll that is set up with CFPB styling in a single cf-vars-overrides file, in which you can override any variable you need to. It may not have been that way when you last started a new project, though.

All your points about unclear/missing documentation are definitely well-taken!

[contolini]

@Scotchester Agreed and those two discussion points conveniently align nicely with the two user stories at the top of this page.

[awolfe76]

There's an interesting parallel discussion thing happening now. @awolfe76 is talking mostly about consuming the framework, but @KimberlyMunoz's point (and the driving force between all the "single repo" talk), is about making it easier for contributors to CF.

I think of these as the same, we build it, we use it, we build it while using it. Using it is the only way to understand how/what to contribute back, outside of design change of course. A lot of the things I've seen mentioned, here and in other issues, help all around. Documentation, cleaner build, cleaner structure, etc.

[jimmynotjim]

CFPB styling in a single cf-vars-overrides file

The only issue is when you don't know where a variable came from or what it does. Having everything in one vars file would make it a lot easier to understand relationships, especially when we use one variable as the value for another variable.

[Scotchester]

The only issue is when you don't know where a variable came from or what it does. Having everything in one vars file would make it a lot easier to understand relationships, especially when we use one variable as the value for another variable.

I'm not clear what you're proposing. How do all the vars get more in a single file?

[awolfe76]

Not to speak for @jimmynotjim ... but from a contributing stand point they aren't in one file. They are scattered through repos and difficult to track down.

When consuming and using the generator, yes, one file can't be made smaller. 😉

[Scotchester]

@awolfe76 Yeah, clarified that with @jimmynotjim via chat. Again, the consumption/contribution tension...

I suggest that we put this specific discussion (variables all in one file) on hold until we figure out if the single-repo solution is viable. That will definitely impact what can/can't be done.

[awolfe76]

👍 one step at a time.

[cfarm]

@contolini not sure where else to put this but i added some fixes to yr VZ branch https://github.com/contolini/capital-framework/compare/voltrazord...cfarm:voltrazord?expand=1

[Scotchester]

@cfarm You could submit a PR to his fork with those :)

[contolini]

@cfarm @Scotchester Let's open PRs against cfpb's voltrazord branch because there's some history wonkiness with mine.

[jimmynotjim]

Didn't know which issue was best for this, but just came across MailChimp's Doc site and a few things I think we could borrow. First is breaking apart the more friendly guides and the more technical docs. This would make the project much more approachable to new users while still allowing seasoned users to find code details. Second is the playground. Hosting a live playground on CodePen and embedding them into our site would allow anyone to test out the project, or even just a component, without having to dive in and build it locally, again, making it much more approachable to new users.

[Scotchester]

I believe this is closed now that Voltrazord is done. @jimmynotjim Could you move your last comment to a more doc-centric issue?