Document: 06-git-workflow.md
Version: 1.0.0

Purpose

This document defines the Git workflow used across all Rundown projects.

A standardized Git workflow improves collaboration, reduces merge conflicts, maintains a clean project history, and ensures every project follows a consistent development process.

Repository Hosting

All Rundown repositories are hosted on GitHub.

Each project should have:

• One repository

• One default branch

• Protected production branch

• Pull Request workflow

Direct commits to the production branch are discouraged.

Branch Strategy

Every repository should contain the following permanent branches.

main

Purpose:

Production-ready code.

Rules:

• Always deployable.

• Protected branch.

• No direct commits.

• Changes only through Pull Requests.

develop

Purpose:

Integration branch for ongoing development.

Rules:

• Receives completed feature branches.

• Used for internal testing before production.

• Should remain stable.

Feature Branches

Every new feature should be developed in its own branch.

Naming convention:

feature/navbar-redesign

feature/blog-search

feature/product-filter

feature/payment-integration

Bug Fixes

Naming convention:

fix/mobile-navigation

fix/login-validation

fix/image-loading

Hotfixes

Used only for production issues.

Naming convention:

hotfix/payment-failure

hotfix/security-patch

Hotfixes should be merged into both:

• main

• develop

Chores

Used for maintenance tasks.

Examples:

chore/update-dependencies

chore/refactor-eslint

chore/docker-upgrade

Documentation

Documentation changes should use:

docs/update-handbook

docs/add-api-guide

Branch Lifecycle

Standard workflow:

develop

↓

feature/new-feature

↓

Pull Request

↓

Code Review

↓

Merge into develop

↓

Testing

↓

Merge into main

↓

Deploy

Commit Messages

Rundown follows the Conventional Commits specification.

Format:

type(scope): description

Example:

feat(blog): add category filtering

fix(auth): resolve login redirect issue

docs(seo): update metadata documentation

refactor(products): simplify product service

style(button): adjust spacing

chore(deps): update dependencies

test(forms): add validation tests

Commit Types

Pull Requests

Every Pull Request should include:

• Summary of changes

• Screenshots (if UI changes)

• Related issue (if applicable)

• Testing completed

• Deployment considerations

Pull Requests should remain focused on a single feature or objective.

Large, unrelated changes should be split into separate Pull Requests.

Code Review

Every Pull Request should be reviewed before merging.

Reviewers should verify:

• Code quality

• Readability

• Performance

• Security

• Accessibility

• Consistency with Rundown standards

Code review is intended to improve quality rather than assign blame.

Merge Strategy

Preferred merge method:

Squash and Merge

Reasons:

• Cleaner Git history

• Easier release tracking

• Simpler rollback

• One commit per completed feature

Releases

Production deployments should originate from the main branch.

Each production release should be tagged.

Example:

v1.0.0

v1.1.0

v2.0.0

Semantic Versioning should be used.

.gitignore

Every Rundown project should ignore:

• node_modules

• .next

• .env.local

• .env.production

• logs

• build artifacts

• IDE-specific files

Sensitive information must never be committed to version control.

Best Practices

• Commit frequently.

• Keep commits focused.

• Write meaningful commit messages.

• Avoid committing unrelated changes together.

• Pull regularly from the latest branch.

• Resolve conflicts before opening a Pull Request.

Common Mistakes

Avoid:

• Committing directly to main.

• Combining unrelated features in one branch.

• Large commits with multiple objectives.

• Generic commit messages such as:

update

changes

fix

testing

final

Commit history should clearly describe the evolution of the project.

Summary

A consistent Git workflow ensures that every Rundown project maintains a clean development history, encourages collaboration, and supports reliable deployments.

Following these standards allows projects to scale as the engineering team grows while remaining simple enough for small teams to use effectively.