📜 Autograder Gitflow Guide

1. Introduction

This document introduces the rules for branches and the most common workflows in the autograder project.

2. Branch Naming Rules

First and foremost, it is imperative to understand branch naming rules. A branch name is composed of two main parts: its classification and name, separated by a "/":

<classification>/<name>

A branch classification can be one of the following:

  • feature: Used for developing new features or significant additions to the codebase. These changes introduce new functionality that didn't exist before.
  • fix: For resolving bugs or errors in existing code. The goal is to correct something that's not working as intended without adding new features.
  • hotfix: Specifically for critical and urgent bug fixes that need to be deployed to production immediately. These typically address issues impacting live users or system stability.
  • refactor: For restructuring existing code without changing its external behavior. Refactoring aims to improve code readability, maintainability, or performance.
  • docs: Dedicated to changes related to documentation.
  • chore: Covers routine maintenance tasks and miscellaneous changes, like updating dependencies.
  • preset: Used for applying predefined grading configurations based on subjects.

Main and Development Branches

The main and development branches are special and do not follow the naming convention. The main branch is considered the production branch. Code should not be pushed directly to it; instead, it should first go to development for integration testing.

3. Protected Branches & Code Review

To avoid sudden breaking changes, the main, development, and preset/* branches are protected. All changes must be submitted via a pull request, which must be approved by at least one other person on the project. The developer is responsible for requesting a review.

It's the developer's responsibility to manually delete unused branches that are not part of a merged pull request.

4. Standard Development Workflow

Feature, fix, hotfix, and refactor branches should be merged into development. After successful integration, a pull request should be created to merge development into main. Once approved, the code becomes available for preset branches.

Standard Development Workflow Diagram

5. Urgent Hotfix Workflow

For critical bugs in production, it's permissible to create a pull request directly into main or a specific preset/* branch. However, this should be a last resort; the standard workflow is always preferred to minimize risk.

Urgent Hotfix Workflow Diagram

6. Chore and Docs Workflow

Changes to documentation (docs/*) can be merged directly into main as they pose no risk to the codebase.

Chore branches, however, might cause dependency issues and should follow the standard development flow (merge to development first).

Chore and Docs Workflow Diagram