git

Many of the developers at Monarch Digital have experience working individually on freelance projects. When working individually, you have a lot of freedom to work however you like. When working as part of a team, on the other hand, it is important to standardize some processes to keep everyone same page. Web development with a team presents some unique challenges, including:

  • Supporting multiple developers working on the same code.
  • Making sure code is written to standard.
  • Deploying working code quickly and consistently to multiple environments.

 

Using a Version Control System (VCS) like Git (http://git-scm.com) is the first step to solving these issues. If you are not using a VCS to manage your source code, read What You Need to Know About Release Control to find out why it is necessary. By itself, however, Git can cause more issues and confusion unless a common workflow is agreed upon and used by each developer. At Monarch Digital, we use the Fork/Pull Request workflow described in this post.

This article assumes you are familiar with basic Git commands and usage. For a review checkout our tutorial on basic Git commands.

The Fork/Pull Request workflow

The fork/Pull Request workflow originated with Github and was designed for open source projects. It allows anyone to create a “fork” (copy) of the repository and submit pull requests to the project without needing write access to the primary repository. The project owner can then review and merge contributed pull requests.

It turns out that, in addition to open source projects, this workflow works very well for any team of developers. Each developer is able to work in their own sandbox (fork) and then submit changes in a pull request after testing locally. Many hosted repository services (like Github and Bitbucket) provide visual tools to review and comment on pull requests. This is an excellent workflow for incorporating code reviews. Figure 1 shows the steps and flow of development using the fork/pull request workflow.

Before we delve into the individual steps from Figure 1, let's review some terms:
fork: A fork is just a copy of a repository. In the fork/pull request workflow each developer has a copy of the primary repository.
origin: The "origin" remote refers to your fork of the primary repository
upstream: The "upstream" remote refers to the primary repository
local: Local refers to the working directory where you will make and commit code changes. This could be on your local machine or on a development server.
master: The Git branch containing production code.

For simplicity, I will assume your repository is hosted on Github or Bitbucket. However, these steps will generally work no matter where your repository is hosted. Before following these steps, each developer should create a fork of the primary repository. Click the follow links for more information on setting up a fork on one of the popular hosted repository services:

 

Each developer should also have a unique local environment or development server setup making and testing code changes.

Steps For Setting Up Your Workflow

(please reference figure 1 above for these steps)

1. Before starting work on a new project or task, switch back to the “master” branch with the command git checkout deploy

2. Use git fetch upstream to pull down any new changes from the primary repository. Note that the fetch command only brings down the references and metadata that git uses and does not change any files in your working directory. Alternatively, git fetch --all will fetch changes from all defined remotes.

3. Merge the latest changes into your local working directory with git merge upstream/master. This will update all files in your working directory to match any changes from the upstream repository.

3.1 (optional) Use git push origin master to make sure the master branch on your fork is up to date.

4. Create a new branch for the current task with git checkout -b issue-9999. The branch name should be specific for the task. At Monarch Digital we use a ticket management system and all our development branches are named with the ticket number (eg. issue-9999).

5. Make code changes and test locally.

6. Add all changes to Git’s staging area with git add [files]. The add command is recursive by default and you can specify individual files and directories or add everything with git add ./.

7. Commit all staged files to the repository with git commit -m "Issue #9999 by draenen: did some stuff". You can specify a commit message using the -m flag. Your message should include a short description of the changes you made. At Monarch Digital, we include the ticket number in the commit message for future reference. For large tasks it may be useful to break your work into multiple commits.

It is important to note that, due to the nature of Git as a distributed VCS, the commit only exists in your local repository, No changes have been made to the upstream repository yet.

7.1 (optional) It is possible that while you were working, another developer pushed additional changes to the upstream repository. You can get those changes with git fetch upstream or git fetch --all.

7.2 (optional) If there were changes made to the upstream repository, you can update your working directory with git rebase upstream/master. Rebase is an advanced command. If you are uncomfortable using rebase, you can do a merge instead: git merge upstream/master. For more details on using rebase, see Merge commits and how to prevent them (git rebase).

8. Push your changes to your fork with git push origin issue-9999, This will create a new branch on your fork that contains all the changes you’ve made.

9. Create a pull request from your fork to the primary repository. See:

 

10. At this point, you can send a link for the pull request to another developer to conduct a code review. The reviewer may add comments directly on the pull request.

11. Once the code review is approved, you can merge the pull request into the primary repository. You are now ready to pull the changes to your staging environment for final testing and approval before moving it to production.

Then go back to step 1 to start work on the next task.

Though it may look intimidating at first, the fork/pull request workflow is easy to master and can simplify working with a team of developers. Any time spent learning these processes will surely be gained back later through increased efficiency within your development workflow.

Tags