Contributing to [PROJECT_NAME]

Thank you for your interest in contributing to [PROJECT_NAME]! This document provides guidelines and information for contributors.

🎯 How to Contribute

Reporting Issues

Before creating an issue, please:

1. Search existing issues to avoid duplicates
2. Use the issue template to provide necessary information
3. Include minimal reproduction steps for bugs
4. Provide clear acceptance criteria for feature requests

Submitting Changes

1. Fork the repository and create a new branch from main
2. Follow coding standards and best practices
3. Write tests for new functionality
4. Update documentation as needed
5. Submit a pull request with a clear description

🔧 Development Setup

Prerequisites

• Node.js 18+ LTS
• npm or yarn package manager
• Git 2.30+

Local Development

# Clone your fork
git clone https://github.com/YOUR_USERNAME/[REPO].git
cd [REPO]

# Add upstream remote
git remote add upstream https://github.com/[ORG]/[REPO].git

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Start development server
npm run dev

📝 Coding Standards

JavaScript/TypeScript

• Use TypeScript for all new code
• Follow ESLint configuration - run npm run lint
• Use Prettier for code formatting - run npm run format
• Write JSDoc comments for public APIs
• Prefer functional programming patterns where appropriate

Code Style

// ✅ Good: Clear function names and type annotations
async function fetchUserActivities(userId: string): Promise<Activity[]> {
  const response = await api.get(`/users/${userId}/activities`);
  return response.data;
}

// ❌ Avoid: Unclear naming and missing types
async function fetch(id) {
  const res = await api.get(`/users/${id}/activities`);
  return res.data;
}

Git Commits

We use Conventional Commits for commit messages:

# Format
type(scope): description

# Examples
feat(auth): add user authentication with JWT
fix(api): resolve data validation error
docs(readme): update installation instructions
test(utils): add unit tests for date helpers
refactor(components): simplify button component logic

Commit Types

• feat - New features
• fix - Bug fixes
• docs - Documentation changes
• test - Test additions or modifications
• refactor - Code refactoring without functionality changes
• style - Code style/formatting changes
• perf - Performance improvements
• chore - Build process, dependency updates

🛠️ Git Aliases for Easy Compliance

We've created helpful git aliases to make conventional commits effortless. See git-aliases.md for setup instructions and examples.

# Quick setup examples
git cf "(blog): add internal team blog functionality"  # feat commit
git cd "(infrastructure): define hybrid hosting strategy"  # docs commit
git cx "(sidebar): resolve navigation link issues"  # fix commit

📝 Learning Note

Practice What We Preach: During our documentation setup, we initially used descriptive commit messages instead of following our own Conventional Commits standard. This taught us the importance of:

1. Immediate adoption of standards we define
2. Tool creation to make compliance effortless
3. Regular auditing of our own practices

This learning led to the creation of our git aliases and validation tools.

🧪 Testing Guidelines

Test Requirements

• 95%+ code coverage for new features
• Unit tests for business logic
• Integration tests for API endpoints
• E2E tests for critical user journeys

Writing Tests

// Unit test example
describe('calculatePrice', () => {
  it('should calculate correct price with tax', () => {
    const result = calculatePrice(100, 0.1);
    expect(result).toBe(110);
  });

  it('should handle zero tax rate', () => {
    const result = calculatePrice(100, 0);
    expect(result).toBe(100);
  });
});

// Integration test example
describe('GET /api/activities', () => {
  it('should return paginated activities', async () => {
    const response = await request(app)
      .get('/api/activities?page=1&limit=10')
      .expect(200);
    
    expect(response.body.data).toHaveLength(10);
    expect(response.body.pagination).toBeDefined();
  });
});

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- activity.test.ts

📋 Pull Request Process

Before Submitting

• Tests pass - npm test
• Linting passes - npm run lint
• Types check - npm run type-check
• Documentation updated - Update README, API docs, etc.
• Changelog updated - Add entry to CHANGELOG.md

PR Description Template

## What does this PR do?

Brief description of the changes and their purpose.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Screenshots (if applicable)

Include screenshots for UI changes.

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Tests added for new functionality
- [ ] Documentation updated
- [ ] No breaking changes (or properly documented)

Review Process

1. Automated checks must pass (CI/CD pipeline)
2. Code review by at least one team member
3. Manual testing for significant changes
4. Final approval by project maintainer

🏗️ Project Architecture

Folder Structure

src/
├── components/     # Reusable UI components
├── pages/         # Application pages/routes
├── hooks/         # Custom React hooks
├── utils/         # Utility functions
├── types/         # TypeScript type definitions
├── api/           # API client and endpoints
├── stores/        # State management
└── tests/         # Test utilities and mocks

Design Patterns

• Component Composition - Prefer composition over inheritance
• Custom Hooks - Extract reusable logic into custom hooks
• Type Safety - Use TypeScript strictly, avoid any types
• Error Boundaries - Implement proper error handling
• Performance - Use React.memo, useMemo, useCallback appropriately

🔒 Security Guidelines

Code Security

• Validate all inputs - Never trust user input
• Use parameterized queries - Prevent SQL injection
• Sanitize outputs - Prevent XSS attacks
• Keep dependencies updated - Regular security updates
• Handle secrets properly - Never commit sensitive data

Reporting Security Issues

Do NOT report security vulnerabilities through public GitHub issues. Instead:

1. Email security@juniro.com with details
2. Include steps to reproduce the vulnerability
3. Provide potential impact assessment
4. Allow reasonable time for response before disclosure

📞 Getting Help

Resources

• Documentation: [Link to full documentation]
• API Reference: [Link to API docs]
• Design System: [Link to component library]
• Team Chat: [Internal communication channel]

Contact

• General Questions: Create a GitHub Discussion
• Bug Reports: Create a GitHub Issue
• Security Issues: Email security@juniro.com
• Feature Requests: Create a GitHub Issue with enhancement label

🙏 Recognition

Contributors who make significant contributions will be recognized in:

• Project README acknowledgments
• Release notes and changelogs
• Internal team recognition
• Conference talks and blog posts (with permission)

📄 License & Intellectual Property

By contributing to [PROJECT_NAME], you acknowledge and agree that:

1. All contributions become the exclusive property of Juniro
2. You assign all rights, title, and interest in your contributions to Juniro
3. Your contributions will be subject to Juniro's proprietary license as detailed in the LICENSE file
4. You have the right to make the contributions and they do not violate any third-party rights
5. All code, documentation, and other materials contributed are confidential and proprietary to Juniro

⚠️ IMPORTANT: This project contains proprietary information. By contributing, you agree to maintain confidentiality and not use or disclose any information outside of your authorized role at Juniro.

---

Thank you for contributing to Juniro! Together, we're building amazing experiences for families and providers worldwide. 🚀