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

...

Develop will be treated as

...

current, tested

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

• Commits on this branch will be linear

• Please use main develop instead of “master”, “mainline”“main”, 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 this branch will be linear

• Commits on develop branches should not be squashed, but should be rebased onto mainReleases, representing the latest stable and verified on-car code, and made from this branch

Branches will be dynamically made

...

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

...

with feature/ or bug/ prefix

• Categorize a single ticket into one of the two categories above, and follow the prefix with a short description

  • ie feature/lsm6dso-driver or bug/malloc-patch

• These branches should be merged into develop branches These branches should NOT be merged directly into main unless we are undergoing a crisisvia squash

  • Should be verified at least in software before merge

Releases will be made every time a

...

pr is merged

...

into develop (roughly)

• Release naming conventions should follow Project Name vX.X major.minor.patch

  • i.e. Shepherd BMS v1.0 1.2.4

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

Pull Requests

Pull

...

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

...

requests should be made whenever work for an issue/ticket is complete

They should follow the template provided upon creation

1 ticket == 1 branch == 1 PR

If relevant changes have been pushed into develop since the branch was made, the user should merge develop into their own PR