Contributing

Guidelines and best practices for contributing to the project, including development workflows, code review processes, and release management.

Development Workflow

Getting Started

1. Fork & Clone

   git clone https://github.com/your-username/smart-shelf.git
   cd smart-shelf
   

2. Create Feature Branch

   git checkout -b feature/new-feature
   # or
   git checkout -b fix/bug-description
   

3. Install Dependencies

   pnpm install
   

4. Environment Setup

   cp .env.example .env.local
   # Configure your environment variables
   

5. Start Development

   pnpm dev
   

Branch Naming Convention

• Features: feature/description (e.g., feature/add-product-search)
• Bug fixes: fix/description (e.g., fix/inventory-calculation)
• Documentation: docs/description (e.g., docs/update-api-guide)
• Chores: chore/description (e.g., chore/update-dependencies)

Commit Messages

Follow the Conventional Commits specification:

# Format
<type>(<scope>): <description>

# Examples
feat(products): add search functionality
fix(inventory): resolve stock calculation bug
docs(api): update endpoint documentation
style(components): improve button styling
refactor(auth): simplify user validation
test(products): add unit tests for product service
chore(deps): update Next.js to v14

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Code Standards

TypeScript Guidelines

// Use explicit types for function parameters and return values
export async function createProduct(
  data: CreateProductData
): Promise<Product> {
  // Implementation
}

// Use interfaces for object shapes
interface ProductFilters {
  search?: string
  category?: string
  priceRange?: [number, number]
  inStock?: boolean
}

// Use enums for constants
enum ProductStatus {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  DISCONTINUED = 'discontinued'
}

React Component Guidelines

// Use functional components with TypeScript
interface ProductCardProps {
  product: Product
  onEdit?: (product: Product) => void
  onDelete?: (id: string) => void
  className?: string
}

export function ProductCard({ 
  product, 
  onEdit, 
  onDelete, 
  className 
}: ProductCardProps) {
  return (
    <div className={cn("product-card", className)}>
      {/* Component implementation */}
    </div>
  )
}

// Use memo for performance when needed
export const ProductCard = memo(({ 
  product, 
  onEdit, 
  onDelete, 
  className 
}: ProductCardProps) => {
  // Component implementation
})

Styling Guidelines

// Use Tailwind CSS classes
<div className="flex items-center justify-between p-4 border rounded-lg">
  <h3 className="text-lg font-semibold">{product.name}</h3>
  <span className="text-sm text-gray-500">{product.sku}</span>
</div>

// Use cn() utility for conditional classes
import { cn } from '@/lib/utils'

<button
  className={cn(
    "px-4 py-2 rounded-md font-medium transition-colors",
    variant === 'primary' && "bg-blue-600 text-white hover:bg-blue-700",
    variant === 'secondary' && "bg-gray-200 text-gray-900 hover:bg-gray-300",
    disabled && "opacity-50 cursor-not-allowed"
  )}
  disabled={disabled}
>
  {children}
</button>

Testing Requirements

Unit Tests

// All utility functions must have unit tests
describe('formatCurrency', () => {
  it('formats currency correctly', () => {
    expect(formatCurrency(1234.56)).toBe('$1,234.56')
  })
  
  it('handles edge cases', () => {
    expect(formatCurrency(0)).toBe('$0.00')
    expect(formatCurrency(null)).toBe('$0.00')
  })
})

Component Tests

// Test component behavior, not implementation
describe('ProductCard', () => {
  it('displays product information', () => {
    render(<ProductCard product={mockProduct} />)
    
    expect(screen.getByText(mockProduct.name)).toBeInTheDocument()
    expect(screen.getByText(mockProduct.sku)).toBeInTheDocument()
  })
  
  it('calls onEdit when edit button is clicked', () => {
    const mockOnEdit = jest.fn()
    render(<ProductCard product={mockProduct} onEdit={mockOnEdit} />)
    
    fireEvent.click(screen.getByRole('button', { name: /edit/i }))
    expect(mockOnEdit).toHaveBeenCalledWith(mockProduct)
  })
})

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run E2E tests
pnpm test:e2e

Code Review Guidelines

What to Look For

1. Functionality: Does the code work as intended?
2. Performance: Are there any performance issues?
3. Security: Are there any security vulnerabilities?
4. Maintainability: Is the code easy to understand and modify?
5. Testing: Are there adequate tests?
6. Documentation: Is the code well-documented?

Review Checklist

• Code follows project conventions and style guide
• No console.log statements in production code
• Error handling is implemented appropriately
• TypeScript types are properly defined
• Components are properly tested
• Documentation is updated if needed
• No security vulnerabilities introduced
• Performance impact is considered
• Breaking changes are documented

Providing Feedback

# Good feedback examples

## Suggestion
Consider using `useMemo` here to avoid recalculating on every render:
```tsx
const filteredProducts = useMemo(() => {
  return products.filter(product => product.category === selectedCategory)
}, [products, selectedCategory])

Question

Why are we using any type here? Could we define a more specific interface?

Nitpick

Minor: Consider using a more descriptive variable name than data.

Blocking

This introduces a security vulnerability. We need to validate user input before processing.

## Pull Request Process

### Creating a Pull Request

1. **Write a Clear Title**

feat(products): add advanced search functionality

2. **Provide Detailed Description**
```markdown
## Changes
- Added search by name, SKU, or category
- Implemented debounced search input
- Added filter by price range
- Added sort by price, name, or date

## Testing
- Added unit tests for search logic
- Added E2E tests for search functionality
- Tested with large datasets (1000+ products)

## Screenshots
[Include screenshots of UI changes]

## Breaking Changes
None

## Checklist
- [x] Tests added/updated
- [x] Documentation updated
- [x] No breaking changes
- [x] Follows code style guidelines

3. Request Appropriate Reviewers
   • At least one maintainer
   • Domain experts for specialized areas
   • New contributors should request senior team members

Review Process

1. Automated Checks

   • All CI tests must pass
   • Code coverage must meet minimum threshold
   • Build must succeed

2. Code Review

   • At least one approval required
   • Address all review comments
   • Resolve all conversations

3. Final Checks

   • Rebase if needed
   • Squash commits if requested
   • Update documentation

Contribution Types

Bug Fixes

1. Reproduce the Issue

   • Create a minimal reproduction case
   • Document steps to reproduce
   • Include environment details

2. Fix Implementation

   • Keep changes minimal and focused
   • Add regression tests
   • Update documentation if needed

3. Example Bug Fix PR

   ## Bug Fix: Inventory calculation error
   
   ### Problem
   Inventory totals were incorrect when products had zero quantity.
   
   ### Root Cause
   The calculation was treating `0` as falsy and skipping those products.
   
   ### Solution
   Changed condition from `if (product.quantity)` to `if (product.quantity !== null)`.
   
   ### Testing
   - Added unit tests for zero quantity scenario
   - Verified fix in development environment
   

New Features

1. Discussion First

   • Open an issue to discuss the feature
   • Get feedback from maintainers
   • Align on implementation approach

2. Implementation

   • Follow existing patterns
   • Include comprehensive tests
   • Update documentation
   • Consider performance impact

3. Feature PR Template

   ## New Feature: Product Analytics Dashboard
   
   ### Description
   Adds a comprehensive analytics dashboard showing:
   - Sales trends over time
   - Top performing products
   - Inventory turnover rates
   - Revenue by category
   
   ### Implementation
   - New `/analytics` route with server-side data fetching
   - Reusable chart components using Chart.js
   - Responsive design for mobile and desktop
   - Real-time data updates using Server-Sent Events
   
   ### Testing
   - Unit tests for analytics calculations
   - Component tests for chart rendering
   - E2E tests for user interactions
   

Documentation

1. Types of Documentation

   • API documentation
   • Component documentation
   • Setup guides
   • Troubleshooting guides

2. Documentation Standards

   • Use clear, concise language
   • Include code examples
   • Add screenshots for UI changes
   • Keep documentation up to date

Release Process

Versioning

We follow Semantic Versioning (semver):

• Major (1.0.0): Breaking changes
• Minor (0.1.0): New features (backwards compatible)
• Patch (0.0.1): Bug fixes (backwards compatible)

Release Steps

1. Prepare Release

   # Create release branch
   git checkout -b release/v1.2.0
   
   # Update version
   npm version minor
   
   # Update CHANGELOG.md
   # Include all changes since last release
   

2. Update Changelog

   ## [1.2.0] - 2024-01-15
   
   ### Added
   - Advanced product search functionality
   - Bulk operations for inventory management
   - Export data to CSV feature
   
   ### Changed
   - Improved performance of product listing page
   - Updated UI components to use new design system
   
   ### Fixed
   - Fixed inventory calculation bug
   - Resolved login redirect issue
   
   ### Deprecated
   - Old API endpoints (will be removed in v2.0.0)
   

3. Create Release

   # Push release branch
   git push origin release/v1.2.0
   
   # Create and push tag
   git tag v1.2.0
   git push origin v1.2.0
   
   # Merge to main
   git checkout main
   git merge release/v1.2.0
   git push origin main
   

4. Deploy

   • Automatic deployment via Vercel/CI
   • Monitor for issues
   • Rollback if necessary

Post-Release

1. Monitor Performance

   • Check error rates
   • Monitor response times
   • Review user feedback

2. Update Documentation

   • Release notes
   • Migration guides (if needed)
   • API documentation

3. Communicate Changes

   • Team notifications
   • User announcements
   • Update project roadmap

Getting Help

Resources

• Documentation: Check existing docs first
• Issues: Search existing issues for similar problems
• Discussions: Use GitHub Discussions for questions
• Slack/Discord: Join team communication channels

Reporting Issues

## Bug Report Template

### Expected Behavior
What should happen?

### Actual Behavior
What actually happens?

### Steps to Reproduce
1. Go to...
2. Click on...
3. See error

### Environment
- OS: [e.g., macOS 14.0]
- Browser: [e.g., Chrome 120]
- Node.js: [e.g., 18.17.0]
- Package version: [e.g., 1.2.0]

### Additional Context
Add any other context about the problem here.

Questions and Support

• Use GitHub Discussions for general questions
• Use Issues for bug reports and feature requests
• Tag appropriate team members for urgent issues
• Be respectful and patient with responses

Thank you for contributing to the project! 🎉