ctm-dev-workflow

The Development Workflow

The end goal is for the commit history in master to tell a logical and descriptive story about the code

Before moving on, find 30 minutes to watch Stephen Ball’s Deliberate Git talk. This will help you understand how we can make our web development more efficient and sustainable by following this workflow.

This guide will cover 3 facets of the workflow:

  1. Writing code
  2. Generating a clean and thorough commit history
  3. Reviewing and merging code into deployable branches via Pull Requests

The coding process

Always do your work in a feature branch

Remember the 1 rule to, uh, rule them all? Yeah, anything on master is deployable. So your work-in-progress should not be done on master. That’s where feature branching comes in.

  1. Start with a clean master branch that’s deployed on production.

    $ git checkout master
$ git pull origin master

  2. Create your feature branch using a semantically-descriptive name with hyphens as separators Good examples: ci-integration or homepage-refactor Bad examples: matt or updates

    $ git checkout -b my-feature
Switched to a new branch 'my-feature'

Make incremental commits throughout your process

As part of your flow it’s important to create separate commits for logical groups of code. For example, let’s say you’re doing some frontend work on a homepage, and as part of that effort you decide to replace a static styles.css stylesheet with a SASS pipeline. In that case you have at least two related but logically distinct sets of changes: The SASS structure and associated dependences, and then the UI changes that have to be made in the CSS and HTML. Once you had built the SASS pipeline you would want to create a commit for that change, probably titled something like “Implement SASS”. Next you would move on to your UI updates and roll those into a subsequent commit (which likely touches some of the same files), perhaps called “Update homepage widget styling”.

Along the way it is recommended that you incrementally commit your work-in-progress. For this you can use the -m flag in your commit to write a quick commit title directly from terminal. In the example above, when you created the sass/ directory you might have run:

$ git add sass/
$ git commit -m "wip create initial sass directory"

It’s okay that your SASS work was incomplete up to that point. Again, the goal is to make many small commits that can later be combined into more cohesive groupings. Remember - it is always easier to combine tiny commits into a single commit than it is to break a single commit into smaller, more logical commits.

Then, once you have changes on homepage.html, you could follow the same process to isolate that work:

$ git add homepage.html
$ git commit -m "wip initial homepage UI updates"

Even if you had already made changes to homepage.html and sass/, you can still stage those changes and commit them separately by using $ git add [thing(s)-you-want-to-stage] instead of $ git add ., which assumes you want to include all of your local changes into a single commit. You can also add multiple individual things to a single commit. Let’s say that after the pipeline was created you wanted to add a separate SASS file for footer styling. This would consist of at least 2 file changes - the _footer.scss styles and the @import 'footer' declaration in styles.css. Since those changes relate to a single logical item of work it makes sense for them to be in the same commit. To stage them both and commit you can do:

$ git add _footer.scss
$ git add styles.css

OR you can add them both in a single declaration

$ git add _footer.scss styles.css

Of course if those are your only local changes you could still do $ git add . but it’s helpful to know all the different ways to go from local file changes to an update in the Git changelog.

Push your commits to the remote

Even if you’re not done working yet it’s a good idea to push your changes to the GitHub remote. This allows you to get feedback on your work (if desired) and provides a safe backup of your code in case your local branch gets unwieldy.

$ git push origin my-feature

The cleanup process

Once your code changes are complete it’s time to turn the messy commit history into clear stories about the changes you made.

Follow the instructions in rebase.md to rewrite your commit history to provide titles and messages that will be useful for anyone else who might have to work on the app in the future.

The review process

Pull Requests are the cornerstone of the development workflow. They allow us to get feedback on our changes, to isolate work-in-progress from deployed environments, and to

Ultimately your commits from my-feature will need to get merged into master in order for them to be deployed to your application’s Production environment.

Merging code with Pull Requests