As new software engineering students, we are constantly instructed to type in specific git commands in our terminal, fork a repository from a Github page, add another student as a collaborator on the project…etc. But what exactly are Github and Git?
Github came to life in 2008, built with Ruby on Rails (what we’re learning at Flatiron!). Its a web-based hosting service that has many additional features and user-friendly interfaces to facilitate collaboration amongst developers and showcasing your work to the community. While git, on the other hand, is a system software (a command line tool) that keeps track of changes in source code during software development. Combined, the two provide a useful set of tools for software development and technical workflow management.
There is no single correct workflow, but for effective teamwork, it’s essential to decide on a consistent one. Not only does this eliminate unnecessary time resolving conflicts amongst the collaborators’ work, but it also provides a clean and comprehensive history of a project. Github certainly did not invent technical workflow management; however, they did create an incredible UI for developers, making workflow management as seamless and as clear as possible.
There are multiple methods and approaches to defining a workflow. It depends on the team structure, size, preferences, and project type. If you’re not sure where to start, you can adapt one of the common Git workflows. I’ve laid out some of the considerations for each below:
- Basic/Central: only one central repository (i.e. for developing a simple website)
- Feature Branch: independent “tracks” of developing a project. Branch created for each individual feature/issue/bug…etc. (collaborators have equal position & knowledge)
- Feature Branch & Merge Requests: Before a branch is pushed to master, it needs to be checked and verified. (involves a hierarchy in the team structure)
- Gitflow: employs two parallel long-running branches — Master & Develop. (used for much larger projects)
- Forking Flow: every time the developer wants to make a change, fork the repository instead of directly cloning. When finished, create a pull request to merge the changes. (for open source projects)
For more detailed information on the different workflows, check out the tutorial here.
As Flatiron School students, we employ the Feature Branch workflow in our projects, so I‘ll focus on explaining this model flow as a starting point.
1. Start with the Master Branch
Say we get a project with two bugs we need to fix. Luckily we have two developers on the team! So, one bug per developer. They should each create a separate feature branch to work on their respective debugging task.
Feature branches are created off the master branch of the repository. To do this, we first have to clone (literally copying) the repository, and make sure that we are on the master branch in our terminal before starting the branch. The “fetch origin” command will pull the latest commits to match your local repo to the most updated version of the project.
We can accomplish this in three commands:
git clone repository_link
git co master
git fetch origin
2. Create your Feature Branch
Now we are ready to create our feature branch! Common convention dictates a separate branch for each feature or issue. There are also naming conventions for the branch name based on the company and the team (ex. ticket number, feature name, bug…etc). checkout -b shortcuts to checkout (switch the branch) and create a new feature branch.
For the cat bug this might look like:
git checkout -b cat_debugger
3. Add, Commit & Push Changes
Every time the developer working on a feature branch writes functional code, I recommend you make a commit (kind of like saving a file) with a message describing the additional code. You can check the state of the working directory and the staging area by running git status. Once oriented, you can use git add . to add all impacted files for committing. Finally you can git commit using the optional -m to include a message. The more commits a developer makes, the more detailed the history of the project will be.
In our example, one the developer removed the antenna from the bug she can check the state of her files and ultimately add her change using three lines:
git add .
git commit -m "antenna removed"
4. Push Feature Branch to Remote
Once ready, you can push up your feature branch to the central repository:
git push -u origin cat_debugger
At this stage, you are giving your fellow team members access to view all your commits (i.e., changes). If you append -u origin branch_name for your first commit to the branch, going forward you can simply type git push since the initial flag adds the feature branch as a remote tracking branch.
5. Create Pull Request
To get feedback on your feature branch, open a pull request. Github gives you this option only if there are differences between your branch and the upstream branch.
To open a pull request:
- On Github: navigate to main page of repository.
- In branch menu, choose branch that contains your commits
3. Click New Pull Request
4. Use base branch dropdown menu to select the branch you’d like to merge your changes into, then use the compare branch to select your feature branch.
5. Include Title & Description of your pull request
6. Create Pull Request
6. Resolve Feedback
Now it’s time to review the code! Usually, there will be one or two developers or managers responsible for testing out the code written on the pull request. These reviewers will pull down the feature branch and test locally (i.e., on their machine) to determine if the code is ready to be merged. If there are changes to be made, the reviewers comment with their suggestions via Github. The developer who created the pull request then resolves these additional comments locally, and pushes the suggested changes.
7. Merge Pull Request
This is probably the scariest part…to avoid complicated merge conflicts, you should make it a habit to work on separate issues/features. Under the repository page, click pull request, and select which branch to merge. Then select Merge Pull request.
Enter a commit message, and confirm the merge. Best practice is to delete the feature branch once merged. This also signifies that this particular case/feature has been closed/completed.
Abstract concepts, such as the way Github and Git function, are hard to grasp at first. I personally find it easiest to comprehend by visualizing these concepts and making them relevant to my situation and environment. After all, these tools were made to facilitate the human experience. I try to remember that Github is just a tool that makes an otherwise potentially disconnected communication amongst team members into an organized and legible system.