The Old Development Workflow

I’m sure I’ve already complained about this a few times, but it bears repeating. Don’t use the diagram shown in Figure 8-1 for your web development workflow. The days of taking a bunch of markup and making it match a PSD file are done, over, dead, and hopefully buried where no one will ever find them again. Frontend development can no longer be putting a nice coat of paint on a mess of HTML; we aren’t here to simply pretty things up.

Figure 8-1. The old development workflow

The New Development Workflow

In stark contrast to the previous workflow, which focused on waterfall handoffs from product owner to UX to development and design to frontend developer, our modern workflow is something completely different. In order to create performant, responsive, accessible websites, we will have to turn this old workflow model on its head. When we do, we get something like the workflow depicted in Figure 8-2.

Figure 8-2. The new development workflow

Frontend Workflow

Moving from the macro to the micro, let’s look at the importance of a good prototyping process and ensuring that your team’s frontend developers are all set up to succeed. Many of these topics are cross discipline, but all of them have a profound impact on the productivity and happiness of your frontend developers.

Now, we can’t make any assumptions about what our developers know or are already equipped with, so our frontend workflow starts as soon as a new developer is hired. It is important to understand all of the steps required for a new developer, sitting down in front of code for the first time, with a new laptop, to write their first line of quality code.

git clone <repo> && cd <repo-name> && make website

Development

Now that we have a story that is focused on updating the system, rather than updating a page, we can proceed in making this contrived, and arguably minimal, change to the design system. We’ve got a button that typically has 8px of padding, and we need to make a variation that has 16px of padding. Let’s take a look at the code we’ll be making changes to:

.cta {
  background: blue;
  color: white;
  padding: 8px;
}

Before our new developer dives into writing some new CSS, let’s have them follow a common and well-accepted practice of creating a feature branch. A feature branch is a Git branch that forks off of your main development branch, and lets you develop and commit code with the intent of eventually merging the feature back into the main branch. The advantage of this approach is that you don’t commit incomplete code to the master branch. You are committing the code in a place where others can check it out and test it before merging it back into your main branch.

With a new feature branch created, it’s now time for the developer to write some CSS! There’s only one problem: there are a ton of ways that our developer could write this CSS.

They could create a completely new button to replace the old one:

.cta-large {
  background: blue;
  color: white;
  padding: 16px;
}

If they are using Sass, they might end up creating a mixin to handle this work and refactor both buttons:

@mixin button($size) {
  background: blue;
  color: white;
  padding: $size;

}

.cta {
 @include button(8px);
}

.cta-large {
 @include button(8px);
}

They could opt to create a button modifier so our button would include both .cta and .cta-large:

.cta-large {
  padding: 16px;
}

/* Example HTML would be <a class="cta cta-large">

Or they could use data attributes instead of classes and write:

.cta[data-size="large"] {
 padding: 16px;
}

/* Example HTML would be <a class="cta" data-size="large">

It should be pretty apparent that even something as simple as creating a new button variation could be accomplished through a number of different approaches. And even though all four of these approaches accomplish the same goal, they each have significantly different effects on the design system that we’re trying to create and maintain.

This is exactly why we spent so much time during the code pillar stage defining the way that we write our selectors, write our CSS, and create element variations. With documentation available to describe our coding practices, the developer will have a guide to creating the correct code and push that new code up to their feature branch.

At this point, the dev’s feature branch is ready for review and they can create a merge request (or pull request) that is equivalent to saying “I’ve got some code that I feel is complete. Can you please review it, then merge it into the main branch?” This takes a bit more time than just merging the code directly into master, but this pull request creates an opportunity for review and feedback to the developer before the code is accepted.

Sometimes this review process discovers a major flaw in the code, or determines that it is not in line with design system expectations. Sometimes the review just provides an opportunity to suggest better ways to write the CSS, optimizations to the Sass functions, or improved clarity to the documentation. Even if the merge just gets a big :thumbsup:, having a second eye on a change to the design system helps to ensure that the code contribution is the best contribution that it could be.

So, now that our developer’s code has been merged into the main branch, it’s time to get this code into production.

Distribution

Our developer has done it! They have written a patch to our current codebase that solved our CTA problem, and after some code review and quality assurance, we are ready to get these changes out to our users. In this case, let’s assume that we chose to create a Sass mixin to create both a .cta button and a .cta-large button. These changes to our Sass files are now committed to master, but that does not guarantee the new CSS has found its way to the live website where users can use it. Before you fire up your FTP client, let’s consider some of the pros and cons of various distribution methods.

Committing Compiled Assets

It is best practice in any version control system to commit only the bare essentials of your code. This means, for example, we tell Git to ignore our temporary files, or any assets that need to download to compile our code (we’ll talk much more about this next chapter). The rationale behind this is that our website doesn’t need those temp files or node modules to perform properly. These files also significantly add to the file size of our project, and they will end up being a constant source of conflicts, as your local temp files might not match up with the ones last committed.

Unfortunately, there is one file type that sits right between “essential to the functionality of the website” and “source of bloat and constant conflicts”: our compiled assets. Any time we compile Sass, CoffeeScript, or LESS; add vendor prefixes with post processors; concatenate some JavaScript files; create an icon font; or process our images to reduce file size, we are creating compiled assets. What are we supposed to do with all of these files? What happens if we commit them? Is it possible to avoid committing them and still have a functioning website?

In many cases, you will find yourself forced to commit these assets. It’s not ideal, but unless you want to ditch your preprocessor and write that CSS file by hand, you might just need to add it to the repo. The advantage of this approach is that your repo always has all of the files required to render properly. If your servers are set up to fetch files directly from the GitHub master branch, you’ll have everything you need to display your website. Another benefit is that if nontechnical users pull down a copy of the site, they can view it without having to go through the lengthy process of setting up the compile tools.

Of course, for this small advantage, we also get to deal with a host of other problems, the greatest of them being merge conflicts. If you’ve ever tried to perform a Git rebase on a project that has compiled assets committed, you’ll know what I’m talking about. Even beyond rebasing, whenever you merge two branches with compiled code, you most likely will be dealing with merge conflicts in those compiled assets. Now, resolving those conflicts is easy (compile everything again and commit that), but this means that you’ll never have a merge request where your frontend devs aren’t pulled in to resolve some merge conflict in the outputted CSS.

If you are hoping to avoid these problems and keep compiled assets out of your codebase, you’ve got a few possible options. Let’s take a look.

Continuous Integration Server

Using a service like Jenkins or Travis CI will provide benefits far beyond the scope of this book, but one of their many uses is to perform operations on our codebase before pushing the code to our production server. What this means is that we can omit our compiled assets from Git and our CI server will perform our compiling tasks for us between checking out our code and pushing that code to production.

This approach offers more than just the convenience of keeping our repository clean—it also helps to protect us from unexpected regressions. If we are committing compiled assets, whenever my feature branch is merged into master, the compiled assets in master are 100% the product of how my machine compiled those assets. Once another developer’s feature branch gets merged in, my feature is going to be rendered with the assets compiled on that developer’s computer.

Sure, other developers will be compiling using my new Sass code and JavaScript files, but there’s always a possibility that differences in our operating systems or system setup or installed software could cause a difference in the compiled code. On the other hand, if we are testing our feature branches using the CI compiled code, and the CI server is compiling the assets pushed to production, we can be confident that those assets will be compiled the same way, every time.

Distribution Channels

If all of your production code is inside of a single repo, you’re probably not worrying too much about distribution channels. But if you are creating a theme or a library or a module that is used by dozens, if not hundreds, of websites, you’ve probably looked into the various distribution channels available to you outside of simple version control. There are more than you might think, and you often have more than one option. Here’s a short, inevitably incomplete list to at least get you started:

• NPM (Node Package Manager)

• Bower

• Ruby Gems

• Composer

• Yeoman Generators

• Drupal Contrib Modules and Drush

• WordPress Plug-ins

• Homebrew

• Sublime Text Package Control

• RPM

• PEAR

Regardless of which type of code you write (PHP, Node, Ruby, CMS module, Mac software, Unix software, VIM plug-in, IDE plug-in), you’ll find that someone has written a package manager for distributing it. Considering that Bower is actually a node module, there are even package managers to manager your package managers! There are several benefits to using a package manager to distribute your code, so having more than we could ever need certainly is better than the alternative.

Package managers provide the following benefits:

Push out versioned releases

This means users of your code won’t automatically be upgraded to the newest release, but instead they can evaluate any new code before upgrading.

Easy for users to know when new releases are available

Most package managers have built-in notifications and internal upgrade systems that make it easy to find upgraded modules and pull down the new code.

Distribute only the files required for the user

You’ll often have a large build system creating your distributed code, and using a package manager allows you to distribute only the files that matter.

Publish code from within a private repository

Sometimes it is not possible to give everyone access to your Git repo. Private version control and firewalls often keep source code under lock and key, even if the end product is meant for general consumption. Package managers allow you to get that distributed code into a public space.

Take some time and look at the various options you have for your project. You’re never locked into a single system (many projects are on Bower and NPM), but you’ll want to be confident in whatever system you decide on, as your users will be creating build systems that depend on this code. So then let’s talk about the build system you’ll be using to create this shareable code, and the systems that rely on code published by others.