In this lesson you'll be taken through the Git workflow you should be following while doing this course.
You'll find plenty of materials on Git workflows online, but what it boils down to in the context of this course is that it's a way to:
- Practice a very common professional developer workflow
- Structure your work in a productive way
- Get GitHub contributions on your profile
- Make it easy for someone (a mentor, colleague, or yourself) to review your work
- Create versions of your projects or try out ideas without committing to them 100%
So, by the end of the course, you'll have experience with one of the most important workflows for any pro developer, you'll be productive, have an attractive GitHub profile, and you'll have experience with the pull request review process.
Next up, you'll get a reminder on Git branches and GitHub pull requests at a high level. Remember to check out the Git & GitHub course if you need a refresher on any of the basics.
What Is a Git Branch
The Git workflow that you'll follow in this course is centered around branches. By the end of the course, you'll have made so many that you won't remember all of them! Just remember to clean up after yourself.
When you work on a Git project, you always have a master or main branch. If you just spin up a repository and start committing, then you're committing to the main branch.
A branch is a separate line of development that allows you to work on different features or bug fixes independently.
Typically, though, the main branch is protected -- any code will need to go through a review process before being committed to the main branch.
Imagine that you're in a team of 50 developers and the main branch is linked to a live website. When you commit to the main branch, the changes go live. You might be able to imagine the issues that could cause.
You don't want anyone and everyone pushing to that. Not only is there a risk that someone will write buggy code (i.e. everyone), but more importantly, everyone will just step on each other's toes.
Parallel Development
The way around this potential mayhem is that everyone works on branches. Say you want to improve the CSS that governs a particular set of buttons on the main page. You might make a feature/button-style branch, and work on that. You can commit to that branch many times and it won't affect the main branch.
Every team and company have different cultures, and some may have very loose requirements for branching and committing to main. On the other hand, some workplaces have other requirements---for instance, where every branch needs to get reviewed, and approved, by at least two people. Not to mention passing any automated testing like linting, and code style checks amongst others.
If everyone works on branches your team mates can work on their own features without having to worry about stepping on each other's toes. If you want someone to help you on your branch, they can work on it too. You may end up working on many branches simultaneously in various stages of readiness.
Once you've finished working on a branch, then you'll want to get it reviewed and merged into the main branch. The way you do this is with a Pull Request.
What Is a GitHub Pull Request
The pull request, or PR for short, is the mechanism used on GitHub to review branches before they're merged to the main branch.
You can merge branches on the Git command line, without needing to go through GitHub. But if you're following the Git workflow and your project is hosted on GitHub, then you'll want to delegate the merging process to GitHub. So once you have your branch, you'll need to go to GitHub's website to continue.
So, you've made a new branch, committed to it, and then pushed the new branch to GitHub. If you go to the repository's page, you'll probably see a notification box appear saying that your new branch has had recent commits. Further, it'll ask you if you want to create a pull request.
You can also create a pull request by going to the Pull requests tab and selecting the big green New pull request button. From there, you'll be asked which branch you want to merge from, and which branch you want to merge to. This will typically be your working branch, to the main branch.
From there, you give your pull request a decent title and description that represents the work contained within the pull request. Then you can create your pull request.
Don't worry about messing up---branches and pull requests are cheap and you can always throw them away if you want.
This will create a unique page with its own URL to track the branch. Now your branch and PR are linked. Any new work you perform on the branch will show up on the PR page.
Once it's created, you can optionally mark it as a draft PR, to indicate that you're still working on it and it's not ready for review. Once it's ready for review, then you request a review from another GitHub user.
Once the review process is over---you'll cover the review process in more detail soon---then the reviewer, owner, or yourself will merge to the main branch from the PR page.
When to Create a New Git Branch
The thing you want to work on will likely take various commits, and will span a few files. It's not a quick typo or bug fix on one line, but something that will take a few and can be grouped together conceptually, for instance:
- Assignments for a chapter
- A bunch of related exercises
- A mini project
- A refactor of some existing code or project
- A new feature you want to add to an existing project
If in doubt, go for small pull requests. It's easier to review a small PR than a huge one.
Most of the time, branches are made from the main branch:
MAIN o-------o
|
NEW BRANCH +-----o-----o
Each o represents a new commit. The new branch was made from the second commit shown in the diagram and has two commits.
When to Create a Pull Request
Once you've worked on the new branch, you make a PR to get it merged back into the main branch, and then you can start a new branch:
ANOTHER NEW BRANCH +---------o
|
MAIN o-------o---------------------o
| | Merge
NEW BRANCH +-----o-----o-----o---+
You don't even have to wait to merge a previous branch to start a new one:
NEW BRANCH +-----o
|
MAIN o-------o
|
NEW BRANCH +-----o-----o-----o
If you are keeping your files conceptually grouped, in the case of this course, then you won't usually be working on the same files in different branches.
That said, you'll probably end up with a merge conflict at one point. That's when two branches have modified the same line in the same file, and when it comes time to merge it, Git needs you to tell it which one to keep.
Resolving merge conflicts is (usually) not as painful as it sounds, but it's best to dive into that once you actually are faced with one. For now, just try not to work on the same files in different branches.
Steps to Follow for the Git workflow
The typical steps that you'll want to follow for this course are:
- Create a new local branch with
git branch <chapter>, where you replace<chapter>with the chapter that you are doing. For instance, the first chapter is in the labs is the01-Introfolder in the02_site_generatorfolder, so you can create a branch called02-01-intro. - Switch to that branch
git switch 02-01-introand start working on your labs. - Commit often! You get a nice GitHub "contribution" for every commit you make, so don't be afraid of making a few commits for every working session. Commit at the very least once a day!
- Push every so often. This just synchronizes the remote repo with your work.
- Create a pull request on GitHub. You can do this by examining your branch in GitHub and you should see the option to create a pull request. These are disposable so create one now just to see what it's like.
- Once you are done, request a review of the pull request. You can do this by visiting the pull request page and on the right-hand side you'll see that you can request a review. Request it from your mentor. You can chat about what to do next and how to get it merged.
- Switch back to your main or master branch and start over for a new chapter! Remember, while the open PR isin't merged, when you go back to the main branch, that work won't be there. That's ok, once you merge the open PRs, everything will get in sync.
With that, you'll be mastering the Git workflow in no time!
Learn by Doing
Practice the Git workflow by creating a new branch to edit your copy of the labs repo. You'll want to change the README file to describe what this repository is for you. You can put something as simple as "This is my labs repository for the Coding Nomads JS 201 course."
Create a pull request (PR), and request a review from your mentor, or if you are going to be reviewing your own work, try out a review.
You'll have to use your judgement for exactly what to create a separate PR for, but generally, if the code is related, then it will usually belong in the same branch/PR.
As a rough guideline, each chapter will likely have one PR. That said, if there's a mini-project with a decent amount of code, then it might make sense to have another PR for that project.
Summary: What is the Git Workflow
- The Git workflow outlined in this lesson provides a structured approach to managing branches, pull requests and reviews for your projects in this course.