Purpose

The objectives of these standards are to:

Maintain a clean and understandable Git history.
Prevent accidental production changes.
Encourage small, reviewable commits.
Reduce merge conflicts.
Ensure every deployment can be traced back to a specific commit.

Scope

These standards apply to every repository within the Cloudberrie GitHub organization, including but not limited to:

cb-manual
cb-website
cb-studio-board

Future repositories must also follow these standards unless an approved exception exists.

Git Identity

Every Cloudberrie engineer must configure Git using the approved engineering identity.

Verify the current configuration:

git config --global user.name
git config --global user.email

Approved configuration:

Name
Cloudberrie Engineering

Email
engineering@cloudberrie.com

Update if required:

git config --global user.name "Cloudberrie Engineering"
git config --global user.email "engineering@cloudberrie.com"

Do not use personal email addresses when committing to Cloudberrie repositories.

Repository Ownership

All engineering repositories are maintained under the GitHub organization:

cloudberrie-studio

Examples include:

cb-manual
cb-website
cb-studio-board

Before beginning work, verify the remote repository:

git remote -v

Branch Strategy

Cloudberrie follows a structured promotion model.

feature/*
      │
      ▼
develop
      │
      ▼
staging
      │
      ▼
main

Branch purposes:

Branch	Purpose
feature/*	Individual features or documentation work
develop	Active integration branch
staging	Pre-production validation
main	Production releases

Direct development on main is not permitted.

Daily Git Workflow

At the beginning of every work session:

git branch --show-current
git status
git pull origin develop

Before making changes, verify:

Correct repository
Correct branch
Clean working tree

Creating Feature Branches

New work should normally begin from the latest develop branch.

git checkout develop
git pull origin develop
git checkout -b feature/<feature-name>

Example:

git checkout -b feature/git-standards

Use descriptive branch names.

Avoid names such as:

feature/test
feature/new
feature/update

Preferred examples:

feature/git-standards
feature/cloudflare-deployment
feature/engineering-overview

Commit Standards

Commits should be:

Small
Focused
Atomic
Easy to review

Each commit should represent one logical change.

Avoid combining unrelated changes into a single commit.

Commit Messages

Commit messages should use the imperative mood.

Good examples:

Add Git Standards documentation

Update Cloudflare deployment guide

Fix broken Engineering Overview route

Create Engineering module structure

Avoid:

changes

update

fixed stuff

misc

work

new changes

A reader should understand the purpose of the commit without opening it.

Reviewing Changes

Before committing:

git status
git diff

Confirm:

Only intended files have changed.
No credentials are included.
No generated files are staged.
No unrelated formatting changes exist.

Staging Changes

To stage all reviewed files:

git add .

To stage specific files:

git add docs/engineering/source-control/git-standards.md

Prefer staging only the files related to the current task when possible.

Local Validation

Before every push:

Run the project validation.

For the Cloudberrie Manual:

npm run build

If the build fails:

Resolve the issue.
Rebuild.
Commit only after the build succeeds.

Commit Process

Standard workflow:

git add .
git commit -m "Add Git Standards documentation"

Review the commit summary before pushing.

Pushing Changes

Push changes to the appropriate branch.

Example:

git push origin develop

After pushing:

Verify the commit on GitHub.
Verify the associated Cloudflare deployment.
Resolve any deployment issues before beginning new work.

Pulling Updates

Regularly synchronize with the remote repository.

git pull origin develop

Do not allow the local branch to drift significantly behind the remote branch.

Merge Conflicts

If Git reports conflicts:

Identify the conflicting files.
Resolve conflicts manually.
Test the project.
Build successfully.
Complete the merge.

Never delete conflict markers without understanding the changes.

Conflict markers:

<<<<<<<
=======
>>>>>>>

must never be committed.

Protected Branches

The following branches are considered protected:

develop
staging
main

Changes should reach these branches only through the approved workflow.

Files That Must Never Be Committed

The following should not be committed unless explicitly required:

node_modules
build
.docusaurus
.env
.env.local
.DS_Store

Always review git status before committing.

Git Ignore

Cloudberrie repositories must maintain an appropriate .gitignore file.

Generated folders, temporary files, local IDE files, and secrets should be excluded.

Large Files

Do not commit:

Videos
Large ZIP archives
Build artifacts
Temporary exports

Large assets should be managed using approved storage locations rather than Git whenever practical.

Best Practices

Commit frequently.
Keep commits focused.
Build before pushing.
Pull regularly.
Use descriptive commit messages.
Verify deployments after every push.
Maintain a clean working tree.

Common Commands

Repository status:

git status

Current branch:

git branch --show-current

Recent commits:

git log --oneline -10

View differences:

git diff

Stage all changes:

git add .

Commit:

git commit -m "Your message"

Push:

git push origin develop

Pull:

git pull origin develop

Troubleshooting

Wrong Branch

Check:

git branch --show-current

Switch if required:

git checkout develop

Wrong Commit Email

Verify:

git config --global user.email

Correct it:

git config --global user.email "engineering@cloudberrie.com"

Unexpected Files

Review:

git status

Inspect:

git diff

Never commit files you do not understand.

Build Fails

Do not push.

Resolve the issue first.

For Docusaurus projects:

npm run build

must succeed before pushing.

Revision History

Version	Date	Summary
1.0	July 2026	Initial Cloudberrie Git Standards