Git Workflow & Contribution

This guide covers how to work with the repository responsibly, keep your fork updated, and manage upstream changes.

Table of Contents

1. Initial Setup (Fork & Clone)
2. Keeping Your Fork Updated
3. Advanced: Partial Pulls & Pushes
4. Contribution Guidelines

1. Initial Setup

Step 1: Fork the Repository

Click the Fork button on GitHub to create your own copy of the repository.

Step 2: Clone Your Fork

# Clone your fork (Origin)
git clone https://github.com/YOUR_USERNAME/ci4-core-new.git
cd ci4-core-new

Step 3: Configure Remotes

You need to tell Git about the original repository (Upstream) to fetch updates.

# Add upstream remote
git remote add upstream https://github.com/Bushido2404/hmvc-ci4.git

# Verify remotes
git remote -v
# origin   https://github.com/YOUR_USERNAME/my-new-orject.git (fetch/push)
# upstream https://github.com/Bushido2404/hmvc-ci4.git (fetch/push)

2. Keeping Your Fork Updated

To pull changes from the main project into your local machine and your fork.

Step 1: Fetch Upstream Changes

# Fetch all branches and commits from upstream
git fetch upstream

Step 2: Merge into Your Local Main

# Switch to your main branch
git checkout main

# Merge upstream changes
git merge upstream/main

Step 3: Push to Your Fork

# Update your fork on GitHub
git push origin main

3. Advanced: Partial Operations

Pulling Specific Files/Folders

If you only want to update a specific folder (e.g., `src/app/Modules/Admin`) from upstream without merging everything:

# 1. Fetch upstream
git fetch upstream

# 2. Checkout specific folder from upstream/main
git checkout upstream/main -- src/app/Modules/Admin

# 3. Commit the update
git commit -m "Update Admin module from upstream"

Pushing Specific Branches

You should generally work on feature branches, not main.

# Create a new feature branch
git checkout -b feature/new-login-design

# Make changes...
git add .
git commit -m "Refactor login page design"

# Push ONLY this branch to your fork
git push origin feature/new-login-design

4. Contribution Guidelines

Commit Messages

We follow the Conventional Commits specification:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Formatting, missing semi-colons, etc
• refactor: Refactoring code without changing logic
• test: Adding tests
• chore: Maintenance tasks

Example:

feat(auth): implement #[RequireAuth] attribute
fix(login): resolve password hash mismatch
docs(git): add contribution workflow guide