Contributing
Development Workflow

Development Workflow

Comprehensive guide to the development workflow, tooling, and best practices for contributing to React Kickstart. This covers everything from initial setup to submitting pull requests.

🚀 Getting Started

Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/react-kickstart.git
cd react-kickstart
 
# Add upstream remote
git remote add upstream https://github.com/gavbarosee/react-kickstart.git

Install Dependencies

# Install all dependencies
npm install
 
# Verify installation
npm run test
npm run lint

Verify Setup

# Test CLI functionality
node bin/react-kickstart.js --version
node bin/react-kickstart.js test-setup --yes --framework vite
 
# Run QA validation
node qa-automation/test-runner.js critical --max-configs 5

🔧 Development Tools

Available Scripts

Linting and Formatting:

# ESLint - check for code issues
npm run lint
 
# ESLint - auto-fix issues where possible
npm run lint:fix
 
# Prettier - format code
npm run format
 
# Prettier - check formatting
npm run format:check
 
# TypeScript - type checking (if applicable)
npm run type-check

Pre-commit validation:

# Run all code quality checks
npm run validate
 
# Quick validation (faster subset)
npm run validate:quick

🌊 Git Workflow

Branch Strategy

Branch Naming: Use descriptive branch names that indicate the type and scope of changes.

# Feature branches
git checkout -b feature/add-svelte-support
git checkout -b feature/improve-typescript-generation
 
# Bug fix branches  
git checkout -b fix/redux-template-issue
git checkout -b fix/nextjs-routing-bug
 
# Documentation branches
git checkout -b docs/update-api-guide
git checkout -b docs/add-troubleshooting
 
# Refactoring branches
git checkout -b refactor/simplify-generator-logic
git checkout -b refactor/extract-common-utilities

Commit Convention

Follow Conventional Commits (opens in a new tab) for automated changelog generation:

Standard commit types:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
  • perf: - Performance improvements
  • ci: - CI/CD changes

Pull Request Process

Create Feature Branch

# Start from latest main
git checkout main
git pull upstream main
 
# Create feature branch
git checkout -b feature/your-feature-name

Make Changes

# Make your changes
# Add tests for new functionality
# Update documentation if needed
 
# Commit changes
git add .
git commit -m "feat: add your feature description"

Validate Changes

# Run full validation
npm run validate
npm run test:coverage
npm run test:flags
 
# Run QA tests
node qa-automation/test-runner.js critical

Push and Create PR

# Push to your fork
git push origin feature/your-feature-name
 
# Create pull request on GitHub
# Fill out the PR template completely

🧪 Testing Strategy

Test Pyramid

Unit Tests

// Example generator unit test
import { ViteGenerator } from '../src/generators/vite-generator.js'
 
describe('ViteGenerator', () => {
  let generator
  let mockProjectPath
  
  beforeEach(() => {
    generator = new ViteGenerator()
    mockProjectPath = '/tmp/test-project'
  })
  
  it('should generate package.json with correct dependencies', async () => {
    const userChoices = {
      framework: 'vite',
      typescript: true,
      styling: 'tailwind'
    }
    
    await generator.createPackageConfiguration(mockProjectPath, userChoices)
    
    const packageJson = JSON.parse(fs.readFileSync(path.join(mockProjectPath, 'package.json')))
    
    expect(packageJson.devDependencies).toHaveProperty('vite')
    expect(packageJson.devDependencies).toHaveProperty('typescript')
    expect(packageJson.devDependencies).toHaveProperty('tailwindcss')
  })
  
  it('should create correct file structure', async () => {
    const userChoices = { framework: 'vite', typescript: true }
    
    await generator.createProjectFiles(mockProjectPath, userChoices)
    
    expect(fs.existsSync(path.join(mockProjectPath, 'src/App.tsx'))).toBe(true)
    expect(fs.existsSync(path.join(mockProjectPath, 'vite.config.ts'))).toBe(true)
    expect(fs.existsSync(path.join(mockProjectPath, 'tsconfig.json'))).toBe(true)
  })
})

Integration Tests

// Example integration test
describe('Full Generation Integration', () => {
  it('should generate complete working project', async () => {
    const projectName = 'integration-test-project'
    const userChoices = {
      framework: 'vite',
      typescript: true,
      styling: 'tailwind',
      state: 'redux',
      testing: 'vitest'
    }
    
    // Generate project
    await generateProject(projectName, userChoices)
    
    // Verify project structure
    expect(fs.existsSync(`${projectName}/package.json`)).toBe(true)
    expect(fs.existsSync(`${projectName}/src/App.tsx`)).toBe(true)
    expect(fs.existsSync(`${projectName}/src/store/store.ts`)).toBe(true)
    
    // Verify project builds
    const buildResult = await execAsync('npm run build', { cwd: projectName })
    expect(buildResult.exitCode).toBe(0)
    
    // Verify tests pass
    const testResult = await execAsync('npm test', { cwd: projectName })
    expect(testResult.exitCode).toBe(0)
    
    // Cleanup
    fs.rmSync(projectName, { recursive: true })
  })
})

🔍 Code Review Guidelines

What to Look For

Functionality

  • Does the code work as intended?
  • Are edge cases handled properly?
  • Is error handling comprehensive?

Code Quality

  • Is the code readable and maintainable?
  • Are functions and variables well-named?
  • Is the code properly structured?

Testing

  • Are there adequate tests for new functionality?
  • Do existing tests still pass?
  • Is test coverage maintained or improved?

Documentation

  • Is new functionality documented?
  • Are breaking changes clearly noted?
  • Is the README updated if needed?

Review Checklist

## Code Review Checklist
 
### Functionality ✅
- [ ] Feature works as described in PR
- [ ] Edge cases are handled
- [ ] Error scenarios are covered
- [ ] No breaking changes (or properly documented)
 
### Code Quality ✅
- [ ] Code follows project conventions
- [ ] Functions are focused and well-named
- [ ] No code duplication
- [ ] Proper error handling
 
### Testing ✅
- [ ] New functionality has tests
- [ ] Existing tests still pass
- [ ] Test coverage is adequate
- [ ] QA automation passes
 
### Documentation ✅
- [ ] Code is self-documenting
- [ ] Complex logic has comments
- [ ] README updated if needed
- [ ] Breaking changes documented
 
### Performance ✅
- [ ] No obvious performance regressions
- [ ] Efficient algorithms used
- [ ] Memory usage is reasonable
- [ ] Bundle size impact considered

🚀 Release Process

Automated Releases

React Kickstart uses semantic-release (opens in a new tab) for automated releases:

Version Bumping

Based on commit messages:

  • fix: → Patch version (1.0.1)
  • feat: → Minor version (1.1.0)
  • BREAKING CHANGE: → Major version (2.0.0)

Manual Release Steps

For emergency releases or special cases:

Prepare Release

# Ensure main branch is up to date
git checkout main
git pull upstream main
 
# Run full validation
npm run validate
npm run test:coverage
node qa-automation/test-runner.js comprehensive

Create Release

# Create release branch
git checkout -b release/v1.2.0
 
# Update version manually if needed
npm version patch|minor|major
 
# Push release branch
git push origin release/v1.2.0

Publish Release

# Merge to main after approval
git checkout main
git merge release/v1.2.0
 
# Tag and publish
git tag v1.2.0
git push upstream main --tags
 
# Publish to npm
npm publish

📚 Best Practices

Code Style

Consistency: Follow the established code style and patterns used throughout the project.

  • Use descriptive names for functions, variables, and files
  • Keep functions small and focused on a single responsibility
  • Add comments for complex logic or business rules
  • Follow existing patterns for similar functionality
  • Use TypeScript where beneficial for type safety

Testing Best Practices

  • Write tests first for new functionality (TDD)
  • Test edge cases and error conditions
  • Keep tests isolated and independent
  • Use descriptive test names that explain the scenario
  • Mock external dependencies appropriately

Documentation

  • Update README for user-facing changes
  • Add inline comments for complex logic
  • Document breaking changes clearly
  • Include examples in documentation
  • Keep docs up to date with code changes

📚 Next Steps

Getting Involved:

Need Help?

  • Open an issue for bugs or feature requests
  • Join discussions for questions and ideas
  • Check existing issues before creating new ones

Welcome to the Team: Following this workflow ensures high-quality contributions and helps maintain React Kickstart's excellent standards.

Contributing Overview