I have used Github and Bitbucket for version control of various projects – personal and professional. Both system are extremely easy to use if you are the only developer on a project, but things can get a little more complicated when there are multiple developers involved. In the past four years I have had one week of dedicated training, and unfortuntately, I have run into too many scenarios where I was just glad there was a commit history to roll back to. I am definitely not the only one with a novice understanding of how to use git and version control, especially in a multi-developer scenario.
I volunteered to set up the GitHub repository for our Capstone project, and thought it might be a good idea to put together some GitHub Standards to avoid as many roll-backs and hiccups as possible. I wanted to share this short list of “Do’s and Don’t’s”, some definitions I have found helpful, and an example workflow, in the hopes that it could help another team, enjoy!
DO:
- Select one team member to set up and manage the repository.
- In the repository set up, require at least one other collaborator to review and accept any code changes before they are merged.
- Select one team member to be the “Branch Lead” in charge of merging changes to the main branch.
- Work out of a development branch off of the main branch instead of directly out of the main branch. This creates a “safe” space to debug and test without sacrificing the main branch with working code.
- Notify other collaborators when a major change is made that might affect a feature or branch that another other collaborator is working on.
- Always add a comment/message to each commit.
DON’T:
- Work directly off of the main branch.
- Allow updates to be pushed to a repo without review of at least one peer.
- Start working on code without understanding the existing code.
- Forget to fetch or pull updates.
- Forget to communicate with other developers on the project.
- End the day with uncommited changes or updates.
- Leave a commit comment blank.
A few helpful definitions
(These definitions from GitHub but are relevant to most version control systems! )
branch: “a parallel version of a repository. It is contained within the repository, but does not affect the primary or main branch allowing you to work freely without disrupting the “live” version”
checkout: “use ‘git checkout’ on the command line to create a new branch, change your current working branch to a different branch, or even to switch to a different version of a file from a different branch”
clone: “a copy of a repository that lives on your computer [locally] instead of on a website’s server…[it] is still connected to the remote version”
collaborator: “a person with read and write access to a repository” all developers on a project should be collaborators, as well as anyone who needs to keep eyes on the project.
commit: “an individual change to a file (or set of files)…usually contain a commit message which is a brief description of what changes were made”
fetch: “[adds] changes from the remote repository to your local working branch without committing them…allows you to review changes before committing them to your local branch”
git: “Git is an open source program for tracking changes in text files”
merge: “takes the changes from one branch (in the same repository or from a fork), and applies them into another. This often happens as a “pull request””
merge conflict: “A difference that occurs between merged branches”
pull: “fetching in changes and merging them” but does it without allowing you to review the changes first.
pull request: “proposed changes to a repository submitted by a user and accepted or rejected by a repository’s collaborators”
push: “send your committed changes to a remote repository”
rebase: “To reapply a series of changes from a branch to a different base, and reset the HEAD of that branch to the result.”
revert: “revert a pull request on GitHub, a new pull request is automatically opened, which has one commit that reverts the merge commit from the original merged pull request”
An Example Workflow
In this simple example, you are a developer working on a Windows machine who is a new collaborator on a repository that has some existing code. Your first order of business is to clone the existing repository to a folder new_dir. After cloning is complete and dependencies are installed, you can checkout the development branch and create a branch of your own off of the development branch to write code and make edits. If you think your edits are ready, checkout the development branch, merge your changes with the development branch and push those changes to the remote repository.
> git clone <remote_url> new_dir
> git checkout dev_branch
> git branch personal_branch dev_branch
# now you are writing code on your personal branch! #
> git checkout dev_branch
> git merge personal_branch
> git push origin
# now that you have merged your personal changes, go to the VCS and create a pull request so that your team cabn review your code#
Once the changes have been pushed, you can go into the VCS and make a pull request (usually a visible tab, you may even be prompted to make one) which allows other collaborators to review your edits before they are officially commited to the repo.
Happy coding!
Resources:
https://docs.github.com/en/get-started/quickstart/github-glossary\
https://www.atlassian.com/git/tutorials/using-branches
https://www.atlassian.com/git/tutorials/making-a-pull-request