@anselmbradford please share what you find!

@contolini can you tell us what you did for HMDA?

Hey all,

We had an issue earlier where we discussed grunt tasks and saw there wasn't really any uniformity in what grunt tasks did what.

This is what @anselmbradford has found from other projects.:

I browsed through some other projects to see what they did around their building tasks. Owning-a-home has build, release, ship, and deploy tasks that are related to building and releasing steps. Eregs uses test, test-js, build, squish. Dash uses build and test, with a default of those two run together (like what Jimmy mentioned). Sentia uses test, testServerSide, frontEndTest, frontAndServerSideTest, and build, which runs the frontAndServerSideTest task. So... the short of it is there's no real cfpb standard that I can see.

Right now this is what Flapjack has

• grunt build - cs, js tasks
• grunt test - unit, macro tests
• grunt - build and test

Does anyone have any strong thoughts on what grunt tasks should do what for front-end projects or if it makes sense to standardize the basic ones like grunt or grunt build?

I believe that this line on the strict mode explanatory comment is incorrect, given the value of the property.

@anselmbradford @ascott1

@anselmbradford mentioned we could include a checklist of items from the review guide to the PR template for often seen issues. Starting a list here but feel free to add to it (or open the PR adding them).

• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows the standards laid out in this playbook
• Passes all existing automated tests
• New functions include new tests
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged
• Visually tested in supported browsers and devices
• Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)
• Have the assets/docs been built with grunt? (if applicable)

We started a discussion on Microformats vs Schema over in cfgov-refresh#258. It seemed like a larger discussion than we should be having on that PR so I'm bringing it over here.

First, why do we care?

As web pages become increasingly complex, people (read search engines) have attempted to create micro data to make page content easier to parse and index. Microformats was one of the earliest, and it's seen quite a few changes in the last ten-ish years. Schema is the newest, but it's also the one most of the search giants are leaning toward (especially Google).

My Views

I've used both. Microformats is far less invasive to your code base (class name based) and I think much easier to grok. Schema requires a lot of new attributes that most people don't easily understand without using it and you really have to think about how the parts of your page fit together.

Working for an SEO driven shop for the past three years I see the benefit (and downsides) to both. That said, in our very un-scientific experience, Schema seemed to have a better return in both search rankings and user intent (the later is almost more important than the former). If this is our goal I suggest Schema.

Tools

There's a couple of Chrome extensions I've used to make validating my micro data easier. Neither is fancy or visually appealing but they do the job.

Microformats

• https://chrome.google.com/webstore/detail/microformats/oalbifknmclbnmjlljdemhjjlkmppjjl?hl=en

Schema

• https://chrome.google.com/webstore/detail/semantic-inspector/jobakbebljifplmcapcooffdbdmfdbjh?hl=en

Examples (all I could find were schema examples)

After installing those extensions you can navigate to any page in chrome and if it's using either format a small icon will appear in the address bar. Click the icon to expand the results.

• http://github.com - within users/orgs/repos
• http://youtube.com - within users/playlists/videos
• http://squarespace.com/
• http://www.bostonglobe.com/
• http://www.last.fm/music/Florence+%252B+the+Machine
• https://medium.com/

Now discuss! (or not, this is a democracy after all)

Talking to @virtix, he asked me to consider what "1.0" looks like for this guide. Honestly, I think we're pretty close, but here's what I'd like to see:

• A testing guide @imuchnik and @contolini have been doing a lot of work to guide us towards a culture of testing. @anselmbradford has done a lot of research in visual/CSS testing. Let's document that!
• Revisit the CSS/Less guide as it's basically my fork of another guide. What are we missing? Does it represent how we work?
• Some recommended libraries This might be treading in dangerous waters, but it also might be nice to say "in general we use _ for charts" etc.

What else could or should be included here?

How are we using it, how can we use it better + more deliberately?

Initial discussion

• Jimmy shared this task documentation format we could use for Readme's: https://github.com/wp-evolved/evolved-theme#available-grunt-tasks
• Maybe grunt is the worst at this and we should use another tool like Gulp
• How do you use grunt on CFPB projects? Share here: https://github.com/cfpb/front-end/wiki/Gruntfile
• Some projects are cleaning up their Gruntfile, please post any related PR's for discussion

We have general gruntfile that we use in Capital Framework. We should link to it somewhere in the guide.

Related to #14

A question as to who should be merging PRs came up in #35. The dev manual says:

Don’t: Merge your own pull requests!

But within Flapjack we've found there are a few good reasons to merge your own requests after the appropriate number of sign-offs (we chose two reviewers)

• gives author a chance to cleanup and squash any edits (if desired);
• fix conflicts (sometimes there's a conflict, you fix it, then no one get's around to merging and new conflicts come up, creating a cycle of "please fix conflict" comments and related commits);
• merge when appropriate (sometimes multiple PRs need to go together).

In addition to this, merging our own PRs after being properly reviewed follows the bit about being trusted as a technology professional discussed in the Pain Points issue - https://[GHE]/sheltonw/2014-performance-kanban/issues/63#issuecomment-38650

Just saw this and thought some on here might be interested: https://github.com/johnpapa/angular-styleguide

Feel free to close this issue whenever.

Moving this discussion from issue #9.

From @anselmbradford

Along the lines of what @mistergone is saying, what about a jshint model that hints at what should be updated, but doesn't update the files directly? I'm not sure on requiring git hooks, but having an easy to turn them on would be nice.

and @jimmynotjim

Looks like grunt-recess and grunt-lesslint are the main linters people are using (going by NPM downloads). Recess also seems to have a SublimeLinter plugin for doing auto-linting.

I came across this today: https://github.com/csscomb/csscomb.js

It looks like a really interesting way to "lint" our CSS. I love that we could configure it to sort properties.

CSS property order guidelines should explain the reasoning for the recommendation

We have some internal documentation on unit testing - let's clean those up/modernize them and move them here.

Let's use this issue to discuss markup and template standards as we work towards building our own style guide.

To kick off the discussion, here are some markup style guides:

• Github
• @mdo's Code Guide
• Google
• ThinkUp

Let's use this issue to broadly discuss CSS and LESS standards as we work towards building our own style guide.

To kick off the discussion, here are some example CSS style guides:

• Github
• Google
• @mdo
• Idiomatic CSS
• cssguidelin.es
• ThinkUp
• Mapbox

Are there guides that you particularly like?

Under Media Queries we suggest styling for mobile first and working up using min-width. This isn't always the best way to organize your styles because if you need to reset a mobile-only style, you're unnecessarily duplicating code.

Here I've made a link a block element as a mobile first baseline but updated to the default styling on larger screens as is recommended.

a {
  display: block;

  .respond-to-min(600px, {
    display: inline;
  });

By simply targeting the small screens only we would reduce our code base and avoid having further over-writes farther down the line.

Ex

a {
  .respond-to-max(599px, {
    display: block;
  });
}

This also means that we can follow the second half of that paragraph and create a baseline that does not require media queries. I'm presuming we're looking for a media query free baseline to automate support for older devices that don't support them. Since these browsers are most likely greater than 600px wide, the second example would automatically support these browsers without any extra work.

Something I've often struggled with is how to organize my code when I'm not using a framework. Frameworks like Backbone can really help with this by forcing you to organize code into models, collections, and views, but it can be more challenging when working with just vanilla JavaScript or jQuery.

A few months ago I worked through the Udacity course JavaScript Design Patterns, which really helped guide my thinking around this. If anyone is remotely interested in this topic, I highly recommend it (at least the first two chapters - before Knockout.js is introduced).

Would this be a good topic for a future front-end meeting? Or even something we want to provide guidance on? In my mind it is related to #55 by @imuchnik.

• Add OSs
• Be more specific about versions
• Additional research needed and/or revisited regularly?

Here's my first pass at an ESLint file. This is totally based on my preferences, so let's discuss what should be added, removed, or changed.

ecmaFeatures:
  ecmascript: 6

env:
  browser: true
  node: true

globals:
  jQuery: true
  $: true

rules:
  # Possible errors
  no-console: 1
  no-extra-parens: 2
  no-irregular-whitespace: 2
  no-reserved-keys: 2

  # Best practices
  block-scoped-var: 2
  curly: 2
  eqeqeq: [2, smart]
  guard-for-in: 1
  no-alert: 2
  no-caller: 2
  no-eval: 2
  no-extend-native: 2
  no-floating-decimal: 2
  no-undef: 2
  no-with: 2
  wrap-iife: [2, inside]

  # Variables
  no-shadow-restricted-names: 2
  no-use-before-define: 2

  # Strict Mode
  strict: [2, "global"]

  # Node.js
  no-mixed-requires: 2

  # Stylistic issues
  brace-style: 2
  camelcase: 2
  new-cap: 1
  no-lonely-if: 2
  no-mixed-spaces-and-tabs: 2
  no-space-before-semi: 2
  no-trailing-spaces: 2
  no-underscore-dangle: 0
  semi: [2, "always"]
  space-after-keywords: 2
  space-in-brackets: [2, never]
  space-infix-ops: 2
  quotes: [2, single]

Here is the documentation for each of the ESLint rules. If you haven't used ESLint before, 0's ignore a rule, 1's produce a warning, and 2's throw an error.

It would be helpful to add a short example code block under the general practices:

.btn,
.btn__big {
  color: #000;
}

We recommend using the JSDoc format for commenting code but we don't mention generating a documentation website from those comments.

JSDoc has a command-line tool that can do it automatically. There's also Docco which is used by hmda-explorer and eRegs used to use it (but stopped?). Does anyone have experience with other documentation generators?

I'm tempted to recommend the JSDoc generator buuuut the website it generates is ugly. We could create a custom template if anyone has the time/inclination.

Thoughts/opinions/anecdotes?

What constitutes a good code review?

So I was chatting with @contolini about frontendbuild.sh and there are two things to put out into the wider community:

1. In a future world where you can go to any CFPB project and run a single script to get the project dependencies and build the project, should that script be named frontendbuild.sh or something like bootstrap.sh or setup.sh so that one day when that script leaves the front-end land we can have a script that will still be called the same, but will also make sense in a project that didn't have a front-end.

2. Anyone have any thoughts/opinions/issues with a build script that:

• a) clears project dependencies.
• b) installs project dependencies.
• c) runs project configuration (such as grunt build).
  Such a script might look like: https://gist.github.com/anselmbradford/1b87ecfda21325bb37dc

@imuchnik brought up a really interesting discussion today on trying to test React components for Owning a Home. This is something that we should explore a bit, as it seems to be a friction point. Specifically testing React components with Browserify.

Current state

DevDash is using React and testing with Jest, but @contolini strongly suggested we don't do that.

Owning a Home uses Mocha/Chai/Sinon for testing and @imuchnik and @amymok were writing tests for the React components with this setup.

Open questions

Let's try to answer the following:

• What are the current pain points/known issues with testing React components?
• What is our desired workflow for testing React components?

Based on those two questions, let's then explore how other projects test React and hopefully find something that works well for us.

cc: @imuchnik @contolini @cfarm @virginiacc @amymok

Selenium has been a barrier to entry for me for functional testing. I'm really interested in exploring the use of DalekJs.

This paragraph in particular resonates with me:

The process we've been through made me think, how should such a tool represent itself to the developers, how can it be "a nobrainer" for web developers, for the people who build what you see in the internetz, the frontend devs, for everyone?! I came to the conclusion that only JavaScript can be considered as a "common knowledge programming language" in web land.
Also the setup process for running the tools that ran the Selenium tests (Java jrde*whatever, Maven, Ant, jUnit, Eclipse, etc.) was a major pain point in my opinion, I wan't it to be as easy as installing a tool via npm.

As an added bonus Dalek has a Grunt plugin and integrates with Saucelabs.

Let's add a browser testing checklist with as a resource.

Mike left an issue on Capital Framework about discussing our progressive enhancement policy. This is something I'd like to discuss here and eventually have a section on in our standards.

cfpb/capital-framework#12

We talk a lot about what browsers we support and what the experience should be like for them, but what should the experience be for older browsers. I think that for anything where the general public is our audience*, everything should work. By work, I mean forms should submit, pages should render, you should be able to read information and not have anything blocked by a bad layout that you can't remove without opening devtools.

I think there's probably more room for nuance, especially when it comes to what we decide to use polyfills for, what we use vendor prefixes for and what level of support we want to have for older browsers that don't necessarily do cosmetic things like border-radius correctly. I think we already have a solid unspoken standard on these things, but it'd be great to have them in guide.

Some prominent projects at the bureau use the Jinja2 templating awesome_͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇͇sauce. Maybe it's arguably not a front-end thing, but front-ends do work on it. There are some coding style areas where there's ambiguity that would be helpful to standardize. I thought I'd just jot down some areas for discussion:

Nesting jinja markup

Should nesting be indented for easier reading of jinja:

 <div>
    {%- if cond1 %}
        <ul>
        {%- if cond2 %}
            {%- for item in items %}
                <li>
                    {%- if cond3 %}
                        <p>

Or to preserve HTML nesting output:

 <div>
    {%- if cond1 %}
    <ul>
    {%- if cond2 %}
       {%- for item in items %}
       <li>
           {%- if cond3 %}
           <p>

Importing templates

Should templates be imported at the top of the file, or just above where they are used? Note that some templates are only conditionally included, so their implementation appears in if blocks.

Spacing, etc

Should filters be spaced, var | length, or not var|length.

Should parentheses be spaced, macro.render(m), or not macro.render( m ).

Do we have a stance on JSON formatting? Should it be part of this groups purview to set one?

Because... yuck :)

🐰 💨

Currently we use various charting libraries across a range of our projects, used for similar solutions:

• D3 (?)
• Highcharts (HMDA Explorer, Owning a Home)
• Raphael (Paying for College, Claiming Social Security)

We should discuss standardizing on a baseline library and ensure that the entire team has an adequate understanding of the tool we choose. Thoughts? How do we best choose a tool going forward?

Also, note that I'm not suggesting we back port existing applications to a single library, but that we set a standard moving forward.

updated: clarified the "we should discuss" paragraph based on the discussion below. For full transparency, it originally read:

We should standardize on a single library and ensure that the entire team has an adequate understanding of the tool we choose. Thoughts? How do we best choose a tool going forward?

Our internal handbook should point to these guides so that we can ensure they are always up to date.

When the first round of fellows joined the team Grunt was introduced to the front-end build process. Grunt is great and has allowed us to do lots of things (minifying files, optimizing images, bundling js modules, etc.). When gulp started to gain traction we decided that we shouldn't chase the shiny and instead should stick with the more mature task runner.

Now that gulp is reasonably mature and seems to have gained the majority of the market share (and is used by large organizations like Google and Facebook), should we consider switching going forward? What would that look like? Do existing projects continue to use grunt, but new projects have the option to use gulp?

Nowhere in this repo do we mention the Capital Framework. I think we should add something about it to the README along with a link to the documentation site. Thoughts/wording suggestions?

After seeing #56 I thought I would bring this up.

There are plenty of articles debating this.

Some of the same problems from the Grunt vs Gulp issue come up here:

• How would a change happen?
  • New projects can use Sass, switch older projects as time allows?
• Rebuild CF? (I heard Bootstrap is doing this.)
• Have both available as long as the remain relatively the same according to the design manual
  • To me the design manual is the driver here and as long as a site/app meets it we're good
• There are plenty of new players here too (postcss, cssnext, etc)

Full disclosure:

• I prefer Sass (node-sass)
• I have been using it to prototype several projects for HMDA

Let the 🎆 begin.

Say you have a function in JavaScript:

function nifty(thing) {
  return thing * 10000;
}

A javadoc-inspired code comment for that function would look like:

// Does something nifty with thing.
// @param thing [Object] A boring toaster.
// @returns [Object] A hip, modern toaster.
function nifty(thing) {
  return thing * 10000;
}

Now take a Less mixin:

.nifty( @thing ) { 

Is there an equivalent code comment style out there somewhere for Less mixins that documents the parameters for the mixin?

I'm in the middle of a re-organizing cfgov-refresh to use the src / dist layout but have a question for the team. What exactly should be included in /src?

My original plan was to only store files that were compiled in /src. This is how I've generally organized larger site projects in the past. @Scotchester brought up a good point though. Many developers think of the /dist as the set of files needed to run the site and this is how I typically organize smaller projects and libraries.

Are there opinions on one vs the other? Originally I was against keeping everything in /src because that would mean even longer grunt processing while every file is transferred from one location to the other, but it does make sense to keep all the files for actually running the site together. Do we have any examples of projects of this size other than Owning a Home (which keeps everything in /src)?

North is a living standard for project development and may serve as a good starting point for a front-end guide (maybe even would be worthwhile using it directly):

https://github.com/north
https://github.com/north/north

:grey_exclamation:Howdy front-enders:grey_exclamation:

So we haven't really talked about node much, which might be the right thing to do--it isn't strictly a front-end topic (an aside: if you are a front-ender and need your first draught of node, check out the art of node).

That said, many of the tools we use are built on top of node (all of our commonly used build tools and package managers) and so I think we should have a keen interest in getting our node stuff right as we extend/enhance these tools.

Also, with tools like browserify, modules written in node (and managed by npm) can be dropped into the front-end quite easily and so are well within our purview, imo.

So!

Our existing JS standards should translate pretty decently to nodeland, but I think we'd be well-served with some words on "the node way" or generally keeping things modular and automating processes as much as is reasonable (an example of this in the context of testing). I'd also encourage people to publish reusable modules to npm whenever possible, which is strongly in line with our open-source-by-default ethos.

Writing modular code could very well be pulled into its own topic that transcends us front-enders, but since node is so steeped in this approach, if nothing else it could be a good vehicle to launch the discussion. 🚀

I've seen a few projects (I can't remember where/which) require the capital-framework repo as a dependency, since it pulls in all of the other cf components. This seems to be an anti-patern in my eyes and something we should discourage.

Do others agree? If so, should this be added to one of our guides?

As we transition to cf.gov-refresh, we are also building new tools that will live at cf.gov. While Capital Framework does an excellent job of providing us with shared styles and patterns, we run the risk of having individual templates across a range of projects.

For example, if a change is made to the styles of the cf.gov-refresh sidebar nav, we will need to update that change in multiple places. The difficulty of that change could vary wildly in each case, since the markup and styles are not the same.

How can we make sure that our templates stay in sync across projects?

One potential solution would be to have a separate repo that each of our projects pulls in as a dependency (with Bower or npm). This repo would contain base templates and layouts, ensuring that our sites stay in sync. Making a change to a project would be as simple as bumping a dependency #.

Thoughts? Other ideas?

If you write CSS, do you follow our existing CSS property order standards?

CITATION
Property Declaration Grouping and Order

.selector {
    /* Display & Box Model */
    display: inline-block;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;
    overflow: hidden;

    /* Positioning */
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    z-index: 10;

    /* Background */
    background: #000 url('../img/bg.png') no-repeat center top;
    /* Shorthand, if appropriate. Otherwise, background-color 
     * before background-image (e.g., if using CSS3 gradients) */

    /* Foreground */
    /* Alphabetic in this group, with the exception of 
     * declaring line-height immediately after font-size */
    color: #fff;
    font-family: sans-serif;
    font-size: 16px;
    line-height: 1;
    font-style: italic;
    font-weight: bold;
    text-align: right;

    /* Miscellaneous, alphabetic */
    cursor: pointer;
    list-style: none;
}

If so, please share your thoughts on its efficacy.

If not, why not?

I'll start:
No, because I just learned about it, and it wasn't obvious to me when editing existing CSS that there was a property order being followed (despite having used a similar standard in the past).

I have noticed a strong affinity to putting everything in app.js or main.js. While it keeps things tidy and intuitively in one place, it does very little for project clarity. How does everyone feel about arriving at some more standardized project structure and smaller, well named files?

Let's use this issue to broadly discuss JS standards as we work towards building our own style guide.

To kick off the discussion, here are some example JS style guides:

• Idiomatic.js
• airbnb
• Google
• felixge's node style guide

Let's compile a list of all of the libraries and frameworks we use across our projects. List 'em for your project below!

@anselmbradford recommended that there be a project on-boarding guide for each project.

@cfarm then suggested that we create a checklist of "needed documentation" for a project, that should be posted in a single place and easy to find.

Am I missing anything?

What should this checklist include?

This is an issue to discuss the merits and use of different front-end frameworks at CFPB.

Examples:
React
Angular
d3

There's a million. Let's use the good ones.

@contolini and I very briefly talked about this a long time ago...

Wouldn't it be cool if we developed a nodeschool style workshopper for working with the consumer complaint database?

I'm not really sure what that would look like, but let's talk about it here! I'm volunteering to work on this, but I'd like to collaborate with someone on it.

For some inspiration, 18F used the CCDB for a data visualization workshop

We created some core values a while back and I request that we spend some time reviewing these at an upcoming FEWD meeting - not to change them, but to remember them.

Ideas on how exactly to do this?