Version control – ServerIO

This entry is part 3 of 4 in the series Best Practices

Introduction

Git is a widely used distributed version control system that provides powerful tools to manage changes in a codebase, collaborate with other developers, and track the history of a project. As a platform engineer, you will likely work with Git on a daily basis, so it’s important to establish best practices to ensure a smooth and efficient workflow. In this article, we will cover several best practices for using Git as a platform engineer.

Setting up a repository

The first step in using Git is to set up a repository for your project. This can be done either locally or on a remote server, such as GitHub or GitLab. When setting up a repository, it’s important to choose an appropriate name and structure for your project.

To create a new repository on GitHub, for example, you can follow these steps:

Sign in to your GitHub account and click the “+” icon in the top-right corner of the screen.
Select “New repository” from the dropdown menu.
Choose a name and description for your repository.
Select the “Public” or “Private” option, depending on your needs.
Click the “Create repository” button.

Adding protection to the main branch

It’s important to protect the main branch (usually named “master” or “main”) to prevent accidental or unauthorized changes. This can be done by setting up branch protection rules in your repository settings. You can require pull requests to be reviewed before merging, enforce certain checks (such as passing tests or code quality checks) before merging, and limit who can push to the main branch.

To set up branch protection rules on GitHub, for example, you can follow these steps:

Go to your repository’s settings page.
Click on the “Branches” tab.
Select the main branch (e.g. “master” or “main”).
Click the “Edit” button next to “Branch protection rules”.
Choose the protections you want to enable, such as requiring pull request reviews, enforcing status checks, or restricting who can push to the branch.

Branch naming

When creating a new branch, it’s important to choose an appropriate name that reflects the work being done. A common convention is to use a prefix to indicate the type of branch (such as “feature/”, “bugfix/”, or “hotfix/”), followed by a brief description of the work being done. For example, “feature/add-login-page” or “bugfix/fix-typo-in-readme”.

Tagging

Tagging is a way to mark a specific commit as important or significant, such as a release or a milestone in the project. Tags can be annotated (with a message and metadata) or lightweight (just a name). Annotated tags are recommended for releases, as they provide more information about the tag and are easier to search and filter.

To create an annotated tag in Git, you can use the following command:

git tag -a <tagname> -m "<message>" <commit>

Commit messages best practices

Commit messages are an important way to communicate the changes being made to a codebase. Good commit messages should be clear, concise, and provide enough information to understand the change being made. A common convention is to use a short summary in the first line (limited to 50-72 characters), followed by a longer description if needed, and optionally a footer with references to issues or other related changes.

Example:

Add login page

This commit adds a new login page to the website, with a form for entering
username and password. The form is validated on the client side with
JavaScript.

Fixes #123

Using issues to refine the problem before the work is completed

Issues are a way to track and organize work

in your Git repository. They can be used to report bugs, suggest new features, or discuss improvements to the project. Using issues can help refine the problem before the work is completed, as it allows for discussions and feedback from other team members or stakeholders.

To create a new issue in GitHub, for example, you can follow these steps:

Go to your repository on GitHub.
Click on the “Issues” tab.
Click the “New issue” button.
Enter a title and description for the issue.
Optionally assign the issue to a team member, label it, or add it to a project board.
Click the “Submit new issue” button.

Using pull requests to merge in changes

Pull requests are a way to propose changes to a codebase and request them to be merged into the main branch. Pull requests can be reviewed and discussed by other team members before they are merged, which helps ensure the quality of the codebase.

To create a new pull request in GitHub, for example, you can follow these steps:

Go to your repository on GitHub.
Create a new branch for your changes.
Make the desired changes to the codebase.
Commit the changes and push them to the new branch.
Go to the “Pull requests” tab and click the “New pull request” button.
Select the base branch (usually the main branch) and the new branch with your changes.
Enter a title and description for the pull request.
Optionally assign the pull request to a team member, label it, or add it to a project board.
Click the “Create pull request” button.

Using rebase to bring older repositories up to date before raising a PR

Before creating a pull request, it’s important to make sure your branch is up to date with the latest changes in the main branch. This can be done by using the “rebase” command to integrate the changes from the main branch into your branch.

To rebase your branch in Git, you can use the following command:

git checkout <your-branch>
git rebase <main-branch>

This will replay your changes on top of the latest changes in the main branch, creating a linear history of the changes.

Viewing previous commits and editing git history

Git allows you to view the history of a project, including all the previous commits and changes. This can be done using the “git log” command,

which shows a list of all the commits in reverse chronological order.

To view the git log in Git, you can use the following command:

git log

If you need to edit the history of a project, such as removing a commit or changing a commit message, you can use the “git rebase -i” command to interactively edit the history.

To edit the git history interactively in Git, you can use the following command:

git rebase -i <commit>

This will open a text editor with a list of all the commits in your history, allowing you to edit the commit messages or remove commits.

Amending the last commit

If you need to make a quick change to the last commit, such as fixing a typo or adding a file, you can use the “git commit –amend” command to add the changes to the last commit.

To amend the last commit in Git, you can use the following command:

git add <file>
git commit --amend

This will open a text editor with the commit message for the last commit, allowing you to edit it if needed.

Reverting a branch to a previous commit

If you need to revert a branch to a previous commit, such

as to undo a mistake or rollback changes, you can use the “git revert” command. This will create a new commit that undoes the changes introduced by a previous commit.

To revert a commit in Git, you can use the following command:

git revert <commit>

This will create a new commit that undoes the changes introduced by the specified commit.

Keeping a changelog in a repository

A changelog is a file in a repository that documents all the changes made to the project over time. It can help track the evolution of the project, and make it easier for team members and stakeholders to understand what changes have been made and when.

The Keep a Changelog website provides a recommended format for creating a changelog file in a repository, which includes sections for different types of changes, such as “Added”, “Changed”, “Deprecated”, “Removed”, “Fixed”, and “Security”.

Using semantic versioning

Semantic versioning is a system for assigning version numbers to software releases, based on a set of rules for how the version number should be incremented depending on the type of changes made to the codebase.

The Semantic Versioning website provides a specification for semantic versioning, which includes three numbers separated by dots: major, minor, and patch. The major version number is incremented for incompatible changes, the minor version number is incremented for backwards-compatible additions, and the patch version number is incremented for backwards-compatible bug fixes.

Using pre-commit to introduce git hooks

Pre-commit is a tool for introducing git hooks into a repository, which can help validate the codebase before allowing a commit to be made. Git hooks are scripts that are run automatically by Git at certain points in the workflow, such as before a commit is made.

Pre-commit provides a collection of pre-made hooks that can be used to check for common issues, such as trailing whitespace, missing or malformed docstrings, and syntax errors.

To use pre-commit in a Git repository, you can follow these steps:

Install pre-commit using pip:

pip install pre-commit

Create a “.pre-commit-config.yaml” file in the root of your repository, with the desired hooks:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.0.1
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer

Run “pre-commit install” to install the hooks:

pre-commit install

Make a change to the codebase and try to commit it. Pre-commit will run the configured hooks before allowing the commit to be made.

Conclusion

Git is a powerful tool for version control and collaboration, and understanding best practices for using Git can help improve the quality and reliability of a codebase. By setting up a repository, adding protection to the main branch, using branch naming, tagging, and commit messages best practices, using issues and pull requests, and using tools like pre-commit, you can create a more efficient and effective workflow for your team.

A Guide to Git Best Practices for Engineers