---
# System prepended metadata

title: Version Control Best Practices (updated draft 08/02/2023)

---

## Description

Version control refers to the tracking of every change to code under our control. We use Git as our version control system. 
Our best practice is to put all code that we write or generate under version control, though different categories of code should be approached differently. In general, In-house code, generated code, and extensions to  third-party code should be under version control. Third party code should **not** be under version control.


[Edit this section](https://redmine.library.arizona.edu/projects/dev-and-platforms/wiki/Best_Practice_Version_All_Code/edit?section=3)

## Specific Standards

- Once code has been deployed from a repository, keep main/master stable. Any development work should be done in a branch and merged into main/master when complete (the exceptions would be if they are the initial commits of a new repository or if the specific repository does not use branching).
- Currently we use `main` as the default branch name for the sole long-lived branch in the repo.
- By default, use the [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow) Git branching model and workflow.
    - Oneflow is a simplified git workflow. There is one long-lived branch, main/master. You branch off of main/master to create short-lived branches for development, then merge your short-lived branch back into main/master. No need for a dev/develop/development long-lived branch.
    - After commits, rebase your branch with main/master and merge (with `--no-ff` option).
- By default, use `[tracker in redmine]/[ticket #]_something_descriptive` branch nameing convention
- Use [annotated tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging#Annotated-Tags) when deploying with git.
- Name your tags using [semantic versioning](https://semver.org/) style.
- Don't delete deployment tags after you've pushed them to remote.
- Write useful commit messages. Reference issues as much as possible.
- Commits must be “[atomic](https://www.freshconsulting.com/atomic-commits/)”. That is, each logical change should be a separate commit.
    - As an example of atomic commits, whitespace and coding standards changes must be in their own commits. 
- In production/staging/shared dev environments, the git status should come back clean, i.e., empty. Use ignore rules to accomplish this.
- Don't commit user-generated content.
- Don't commit sensitive information like passwords.
- Don’t commit logs or system-generated files.
- Err on the side of committing and pushing to vitae or GitHub more often, normally at least once a day.

[Edit this section](https://redmine.library.arizona.edu/projects/dev-and-platforms/wiki/Best_Practice_Version_All_Code/edit?section=4)

## Rationale

Version control is a foundation of modern development teams. It benefits a team by boosting developer confidence, improving collaboration, and increasing transparency. It protects against developer mistakes, and it serves as a rudimentary deployment tool. Integration with an issue tracking system increases the value.

[Edit this section](https://redmine.library.arizona.edu/projects/dev-and-platforms/wiki/Best_Practice_Version_All_Code/edit?section=5)
