Overview

These are a list of Git guidelines that team members should be held to when contributing to a codebase. Some are just general Git hygiene and others are specific good practices to follow for this team.

Resources

If you are new to git, the following may be helpful to have on you while you learn.

Commits

Commits will only contain relevant files/changes

• There should be no build files, lingering Mac files, VSCode configuration files, etc

• If you accidentally modified another file, make sure you verify that it was intentional before adding that change to the staging area

Commits will contain a logical group of similar changes

• 1 commit, 1 purpose

• Try to avoid single-line commits or overly small commits

• Also try to avoid overly large commits that encompass a large amount of changes

• Commits can be squashed together and renamed via an interactive rebase, but only in develop branches

Commit descriptions will be descriptive of what was actually done

• Please don’t make super short commit messages like fix

Commits will be made on the correct branches

• Run git branch before you commit/push to verify you are working on the right branch

• This avoids having to cherry-pick commits and such

• If this mistake is made, try and correct it before it is pushed to remote

Branches

main will be treated as final

• The main branch should be locked and only able to be changed by leadership

• Please use main instead of “master”, “mainline”, etc for naming the base branch

develop/* will be treated as “main”s for respective development efforts

• The name given to the develop branch should be indicative of the effort

• Commits on develop branches should not be squashed, but should be rebased onto main

Branches will be dynamically made per ticket/fix

• Please prefix the branch with the ticket number followed by a very brief descriptor of what it is

  • i.e. 99-charger-leds, not making-charging-leds-change-based-on-soc

• Commits on smaller branches for tickets/fixes should be squashed as much as is needed

• Any formatting commits should be squashed into a feature commit unless that is the point of the ticket

• These branches should be merged into develop branches

• These branches should NOT be merged directly into main unless we are undergoing a crisis

Releases will be made every time a develop branch is merged in

• Release naming conventions should follow Project Name vX.X

  • i.e. Shepherd BMS v1.0

• Releases should be fully working and contain an executable or a zip file of good, buildable source code

Pull Requests

Pull Requests will be made every time we want to merge into a develop or main branch

Pull Requests will include the ticket number in the description by adding in “#ticket-num”

• i.e. write “Ticket #99”, GitHub will generate a link to ticket 99 in the PR

Pull Requests will include the changes made to the files

Pull Requests will include how the code was tested