Managing version control / branches / pull requests

We use Github to manage our code as a team. Using Github's pull request functionality will ensure that we keep our codebase free of conflicts, while also maintaining a clean history of changes.

Steps

  • For a video overview, click here

Starting with a Github Issue

  • All tasks must start with a Github Issue
    • Go to Issues and click New Issue
    • Write down all the relevant details in the Issue
    • Link your team's project board by clicking "Projects" and selecting the relevant board
  • Once you are starting work on the issue, go to your team's project board and move the Issue to In Progress

Writing your code

  • Whenever you work on a new feature, do not develop on the main branch. By default, you will not be able to push into the main branch.
  • Make sure your repo is up to date with the Github repo, with a git pull
  • Create your own feature branch by navigating to the root of the directory and typing git checkout -b "name-of-feature"
    • Ideally you will just create one branch per feature or issue, to allow for easy merging and code review later on
    • If you are working on a branch that is tied to a Github Issue, then it's best to name the branch after the issue
  • Work on your feature branch as normal and make sure to save all your files
  • Once you are ready to push your code do git add . to stage your files for commit
  • Commit your changes with a message of what you changed with git commit -m "message you want to add"
  • Push your changes with git push origin "name-of-branch". The terminal should return a Github link.
    • Click through to the Github link and you should now be on a Pull Request page.

Submitting a Pull Request

  • Edit the details of your pull request and add your teammates as reviewers
    • You will find that your PR will be pre-loaded with a template
    • Make sure you reference the right issue # when prompted, as this will automatically link your PR with your issue
  • Link the PR to your Github project board by going to "Projects" and selecting your project board
  • Once the PR has been reviewed, the team leader will merge the change into the main branch and safely delete the branch from within Github
    • There might be a chance that you run into a merge conflict. See here on how to deal with merge conflicts on Github.
  • Remember to git pull into your main branch locally to keep everything up to date before working on your next feature

FAQs

Other relevant resources