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
3. Merge the latest changes into your local working directory with
3.1 (optional) Use
4. Create a new branch for the current task with
5. Make code changes and test locally.
6. Add all changes to Git’s staging area with
7. Commit all staged files to the repository with
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
7.2 (optional) If there were changes made to the upstream repository, you can update your working directory with
8. Push your changes to your fork with
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.