Contributing

How to Submit a Pull Request

Complete Guide to Code Contribution

Environment Setup ยท Workflow ยท Standards


๐ŸŽฏ Overview

We use a develop branch-based workflow. All changes should be made on branches created from develop, then submitted as Pull Requests to merge back into develop.

Branch Structure

BranchPurposePR Target
mainStable releaseโŒ Don't PR directly
developActive developmentโœ… PR target branch
feature/*New featuresโ†’ develop
fix/*Bug fixesโ†’ develop
docs/*Documentation updatesโ†’ develop

๐Ÿ”ง Environment Setup

1. Fork Repository

  1. Visit NextJS Base
  2. Click the Fork button in the top right
  3. Select your GitHub account

2. Clone Your Fork

# Clone your fork
git clone https://github.com/your-username/nextjs-base.git
cd nextjs-base

# Add upstream repository
git remote add upstream https://github.com/huglemon/nextjs-base.git

# Verify remotes
git remote -v
# origin    https://github.com/your-username/nextjs-base.git (fetch)
# origin    https://github.com/your-username/nextjs-base.git (push)
# upstream  https://github.com/huglemon/nextjs-base.git (fetch)
# upstream  https://github.com/huglemon/nextjs-base.git (push)

3. Install Dependencies

bun install
cp .env.example .env.local
# Edit .env.local to configure database
bun run init

๐Ÿ“ Workflow

Step 1: Sync Upstream Code

Always start from the latest develop branch:

# Fetch latest code
git fetch upstream

# Switch to develop
git checkout develop

# Sync upstream code
git merge upstream/develop

# Push to your fork (optional)
git push origin develop

Step 2: Create Feature Branch

# Create and switch to new branch
git checkout -b feature/your-feature-name

# Bug fix
git checkout -b fix/issue-description

# Documentation update
git checkout -b docs/documentation-topic

Branch Naming Conventions:

PrefixPurposeExample
feature/New featurefeature/add-dark-mode
fix/Bug fixfix/login-redirect-issue
docs/Documentation updatedocs/update-readme
refactor/Code refactoringrefactor/simplify-auth
test/Test relatedtest/add-user-tests

Step 3: Make Changes

  1. Write code
  2. Follow existing code style and conventions
  3. Add tests if necessary
  4. Update documentation if necessary
# View changes
git status

# Stage changes
git add .

# Commit (use descriptive commit message)
git commit -m "feat: Add dark mode toggle to navbar"

Commit Message Conventions:

PrefixDescription
feat:New feature
fix:Bug fix
docs:Documentation update
style:Formatting, no code logic changes
refactor:Code refactoring
test:Add tests
chore:Build/tool related

Step 4: Push to Your Fork

git push origin feature/your-feature-name

Step 5: Create Pull Request

  1. Open your fork on GitHub
  2. Click Compare & pull request
  3. Ensure base is huglemon/nextjs-base:develop
  4. Fill PR template:
## Description
Briefly describe your changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring

## Testing
Describe how you tested these changes.

## Checklist
- [ ] Code follows project style conventions
- [ ] Changes tested locally
- [ ] Updated relevant documentation (if needed)
- [ ] Changes don't break existing functionality
  1. Click Create pull request

๐Ÿ“‹ Standards

Code Style

  • Follow existing patterns in codebase
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions small and focused

Testing

# Run lint check
bun run lint

# Run type check (if applicable)
bun run typecheck

# Test your changes locally
bun run dev

Documentation

  • Update relevant documentation for new features
  • Add JSDoc comments for new functions
  • Include examples in documentation

๐Ÿ”„ Keep Branch Updated

If develop has new commits during your development:

# Fetch latest code
git fetch upstream

# Rebase your branch onto develop
git rebase upstream/develop

# Force push if needed (only on your own branch!)
git push origin feature/your-feature-name --force-with-lease

โœ… PR Checklist

Before submitting, confirm:

  • Branch created from develop
  • Code follows project conventions
  • Tested locally
  • Updated documentation (if needed)
  • Clear commit messages
  • Complete PR description
  • No merge conflicts

๐Ÿ” After Submission

  1. Wait for Review - Maintainers will review your PR
  2. Handle Feedback - Make changes if requested
  3. PR Merged - Celebrate! ๐ŸŽ‰

If Changes Needed

# Make requested changes
git add .
git commit -m "fix: Address review feedback"
git push origin feature/your-feature-name

PR will update automatically.