Smart Contract Projects: Git Workflow¶

Repository Structure¶

main-project/                           (Node/TypeScript/Hardhat)
├── contracts/<contract-repo>/          (Git submodule - Solidity contracts)
├── diamonds/<DiamondContractName>/     (Git submodule - Deployment records & config)
├── scripts/
├── tests/
├── package.json
├── tsconfig.json
└── hardhat.config.ts

Branch Strategy¶

Main Repositories (Parent + Both Submodules)¶

Core Branches¶

main - Production-ready code, always deployable
staging - Pre-release testing and validation (deployed to testnets)
develop - Integration branch for ongoing development

Supporting Branches¶

feature/CONTRACT-123-add-staking - New features
hotfix/fix-critical-vulnerability - Critical production fixes
release/v1.2.0 - Release preparation

Naming Conventions¶

Branch Names¶

feature/ISSUE-123-brief-description
hotfix/critical-issue-description  
release/v1.2.0
chore/update-dependencies
docs/update-readme

Commit Messages¶

feat(contracts): add staking reward mechanism (#123)
fix(deployment): correct mainnet contract address (#456)
test(staking): add comprehensive staking tests
docs(readme): update deployment instructions
chore(deps): bump hardhat to v2.19.0

Tags¶

v1.0.0          - Major release
v1.1.0          - Minor release  
v1.1.1          - Patch release
v1.0.0-beta.1   - Pre-release

Workflow Process¶

1. Feature Development¶

# Start from develop
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/ISSUE-123-add-governance

# Update submodules to latest develop
git submodule update --remote --merge

# Work on feature...
# Make commits following conventional commit format

# Push feature branch
git push -u origin feature/ISSUE-123-add-governance

2. Pull Request Requirements¶

PR Title Format¶

feat: Add governance token staking mechanism (#123)
fix: Resolve deployment configuration for Polygon (#456)

Required PR Checks¶

[ ] All tests pass (unit + integration)
[ ] Smart contracts compile without warnings
[ ] Gas optimization review completed
[ ] Security considerations documented
[ ] Deployment plan updated (if applicable)
[ ] Documentation updated
[ ] Submodule versions properly updated

PR Template¶

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Smart Contract Impact
- [ ] New contracts added
- [ ] Existing contracts modified
- [ ] Deployment configuration changed
- [ ] Gas cost implications

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Mainnet fork testing completed

## Deployment Checklist
- [ ] Deployment scripts updated
- [ ] Configuration files updated
- [ ] Migration strategy documented

## Security Review
- [ ] No new attack vectors introduced
- [ ] Access controls reviewed
- [ ] Third-party integrations validated

3. Submodule Management¶

Updating Submodules in Parent¶

# Option A: Update to latest commit on develop
git submodule update --remote --merge

# Option B: Update to specific commit
cd contracts
git checkout feature/new-contract
cd ..
git add contracts
git commit -m "feat: update contracts submodule to include new staking contract"

Submodule Workflow Rules¶

Contracts submodule: Always merge to develop first, then update parent
Deployments submodule: Updated immediately after successful deployments
Atomic updates: Submodule updates should be separate commits with clear messages

4. Release Process¶

Creating a Release¶

# Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# Update version numbers, changelogs
# Final testing and bug fixes only

# Merge to main
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"

# Merge back to develop
git checkout develop
git merge --no-ff release/v1.2.0

# Clean up
git branch -d release/v1.2.0

GitHub Integration¶

Branch Protection Rules¶

Main Branch¶

Require pull request reviews (min 1 reviewer)
Require status checks to pass
Require branches to be up to date
Require conversation resolution
Restrict pushes to admins only

Develop Branch¶

Require pull request reviews (min 1 reviewer)
Require status checks to pass
Allow force pushes for admins

GitHub Actions Workflow¶

# Example CI/CD triggers
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    # Run tests, linting, security checks

  deploy-testnet:
    if: github.ref == 'refs/heads/develop'
    # Auto-deploy to testnet

  deploy-mainnet:
    if: github.ref == 'refs/heads/main'
    # Manual deployment to mainnet

Issue and Project Integration¶

Issue Labels¶

Type:
- bug
- feature
- security
- gas-optimization
- documentation

Priority:
- critical
- high
- medium
- low

Component:
- contracts
- deployment
- testing
- infrastructure