rxminder/CONTRIBUTING.md

# Contributing to Medication Reminder App

Thank you for your interest in contributing to the Medication Reminder App! This document provides guidelines and information for contributors.

## 🤝 How to Contribute

### Reporting Issues

Before creating an issue, please check if it already exists in our [issue tracker](https://github.com/your-username/rxminder/issues).

#### Bug Reports

- Use the bug report template
- Include steps to reproduce
- Provide system information
- Add screenshots if applicable

#### Feature Requests

- Use the feature request template
- Explain the problem you're trying to solve
- Describe your proposed solution
- Consider implementation complexity

### Development Process

#### 1. Fork and Clone

```bash
# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/rxminder.git
cd meds

# Add upstream remote
git remote add upstream https://github.com/original-owner/meds.git
```

#### 2. Set Up Development Environment

```bash
# Run setup script
./setup.sh

# Or manual setup
bun install
cp .env.example .env
# Edit .env with your development values
docker compose -f docker/docker-compose.yaml up -d
```

#### 3. Create Feature Branch

```bash
# Update main branch
git checkout main
git pull upstream main

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

#### 4. Make Changes

- Follow coding standards (see below)
- Write tests for new functionality
- Update documentation as needed
- Ensure all tests pass

#### 5. Commit Changes

```bash
# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add medication interaction checking

- Implement drug interaction API integration
- Add warning UI components
- Include interaction severity levels
- Update medication form validation"
```

#### 6. Push and Create Pull Request

```bash
# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub
# Use the pull request template
# Link related issues
```

## 📝 Coding Standards

### TypeScript/JavaScript

```typescript
// Use TypeScript for all new code
// Define interfaces for data structures
interface Medication {
  _id: string;
  name: string;
  dosage: string;
  frequency: Frequency;
}

// Use meaningful variable names
const medicationList = getMedications();
const isUserAuthenticated = checkAuthStatus();

// Add JSDoc comments for complex functions
/**
 * Calculates medication adherence percentage
 * @param takenDoses - Number of doses taken
 * @param totalDoses - Total number of scheduled doses
 * @returns Adherence percentage (0-100)
 */
function calculateAdherence(takenDoses: number, totalDoses: number): number {
  return totalDoses > 0 ? (takenDoses / totalDoses) * 100 : 0;
}
```

### React Components

```tsx
// Use functional components with hooks
import React, { useState, useEffect } from 'react';

interface MedicationCardProps {
  medication: Medication;
  onEdit: (medication: Medication) => void;
  onDelete: (id: string) => void;
}

export const MedicationCard: React.FC<MedicationCardProps> = ({ medication, onEdit, onDelete }) => {
  const [isLoading, setIsLoading] = useState(false);

  // Use descriptive event handlers
  const handleEditClick = () => {
    onEdit(medication);
  };

  const handleDeleteClick = async () => {
    setIsLoading(true);
    try {
      await onDelete(medication._id);
    } finally {
      setIsLoading(false);
    }
  };

  return <div className='medication-card'>{/* Component JSX */}</div>;
};
```

### CSS/Styling

```css
/* Use BEM methodology for CSS classes */
.medication-card {
  border: 1px solid var(--border-color);
  border-radius: 8px;
  padding: 16px;
}

.medication-card__header {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.medication-card__title {
  font-size: 1.2rem;
  font-weight: 600;
  margin: 0;
}

.medication-card--highlighted {
  border-color: var(--primary-color);
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* Use CSS custom properties for theming */
:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --success-color: #28a745;
  --warning-color: #ffc107;
  --danger-color: #dc3545;
}
```

### File Organization

```
src/
├── components/          # Reusable UI components
│   ├── common/         # Generic components
│   ├── forms/          # Form-specific components
│   └── modals/         # Modal components
├── pages/              # Page-level components
├── hooks/              # Custom React hooks
├── services/           # API and business logic
├── utils/              # Utility functions
├── types/              # TypeScript type definitions
├── contexts/           # React context providers
└── assets/             # Static assets
```

## 🧪 Testing Guidelines

### Unit Tests

```typescript
// Test filename: ComponentName.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { MedicationCard } from './MedicationCard';

describe('MedicationCard', () => {
  const mockMedication = {
    _id: '1',
    name: 'Aspirin',
    dosage: '100mg',
    frequency: Frequency.Daily
  };

  const mockOnEdit = jest.fn();
  const mockOnDelete = jest.fn();

  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('renders medication information correctly', () => {
    render(
      <MedicationCard
        medication={mockMedication}
        onEdit={mockOnEdit}
        onDelete={mockOnDelete}
      />
    );

    expect(screen.getByText('Aspirin')).toBeInTheDocument();
    expect(screen.getByText('100mg')).toBeInTheDocument();
  });

  it('calls onEdit when edit button is clicked', () => {
    render(
      <MedicationCard
        medication={mockMedication}
        onEdit={mockOnEdit}
        onDelete={mockOnDelete}
      />
    );

    fireEvent.click(screen.getByRole('button', { name: /edit/i }));
    expect(mockOnEdit).toHaveBeenCalledWith(mockMedication);
  });
});
```

### Integration Tests

```typescript
// Test authentication flow
describe('Authentication Integration', () => {
  beforeEach(() => {
    // Clear localStorage and reset mocks
    localStorage.clear();
    jest.clearAllMocks();
  });

  it('allows user to register and login', async () => {
    // Test registration
    const registrationResult = await authService.register('test@example.com', 'Password123!', 'Test User');

    expect(registrationResult.user.email).toBe('test@example.com');
    expect(registrationResult.user.status).toBe(AccountStatus.PENDING);

    // Test email verification
    await authService.verifyEmail(registrationResult.verificationToken.token);

    // Test login
    const loginResult = await authService.login({
      email: 'test@example.com',
      password: 'Password123!',
    });

    expect(loginResult.user.status).toBe(AccountStatus.ACTIVE);
    expect(loginResult.accessToken).toBeDefined();
  });
});
```

### Running Tests

```bash
# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run specific test file
bun test MedicationCard.test.tsx

# Run tests with coverage
bun test --coverage

# Run integration tests
bun run test:integration

# Run E2E tests with Playwright
bun run test:e2e

# Run E2E tests in UI mode
bun run test:e2e:ui

# Debug E2E tests
bun run test:e2e:debug

# Run all tests (unit + integration + e2e)
bun run test:all
```

### E2E Testing

E2E tests use Playwright and are located in `tests/e2e/`. When adding new features:

```typescript
// Use custom fixtures for authenticated testing
import { test } from './fixtures';

test('should perform user action', async ({ adminPage }) => {
  // Test implementation with auto-logged-in admin
});
```

See [tests/e2e/README.md](tests/e2e/README.md) for detailed E2E testing guidelines.

## 📚 Documentation Standards

### Code Documentation

- Add JSDoc comments for all public functions
- Document complex algorithms and business logic
- Include examples for utility functions
- Keep comments up-to-date with code changes

### API Documentation

- Document all endpoints with examples
- Include request/response schemas
- Specify error codes and messages
- Provide authentication requirements

### User Documentation

- Write clear setup instructions
- Include troubleshooting guides
- Provide usage examples
- Keep screenshots current

## 🔍 Code Review Process

### Before Requesting Review

- [ ] All tests pass locally
- [ ] Code follows style guidelines
- [ ] Documentation is updated
- [ ] No console.log statements
- [ ] Secrets are not committed
- [ ] Performance impact considered

### Review Checklist

- [ ] Code is readable and well-structured
- [ ] Tests cover new functionality
- [ ] Security implications considered
- [ ] Accessibility requirements met
- [ ] Browser compatibility verified
- [ ] Mobile responsiveness checked

### Review Response

- Be open to feedback
- Ask questions for unclear comments
- Address all review comments
- Update documentation if needed
- Test suggested changes

## 🚀 Release Process

### Version Numbering

We follow [Semantic Versioning](https://semver.org/):

- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Release Checklist

- [ ] Update CHANGELOG.md
- [ ] Update version in package.json
- [ ] Run full test suite
- [ ] Update documentation
- [ ] Create release notes
- [ ] Tag release in Git
- [ ] Deploy to staging
- [ ] Validate staging deployment
- [ ] Deploy to production

## 🎯 Development Priorities

### High Priority

- Bug fixes and security issues
- Performance improvements
- Accessibility enhancements
- Core functionality stability

### Medium Priority

- New features and enhancements
- Developer experience improvements
- Documentation updates
- Test coverage improvements

### Low Priority

- Code refactoring
- Minor UI improvements
- Non-critical feature requests
- Experimental features

## 🛠️ Development Tools

### Required Tools

- **Node.js 18+** or **Bun 1.0+**
- **Docker and Docker Compose**
- **Git**
- **Code Editor** (VS Code recommended)

### Recommended Extensions (VS Code)

- TypeScript and JavaScript Language Features
- ESLint
- Prettier
- Docker
- GitLens
- Thunder Client (for API testing)

### Useful Commands

```bash
# Development
bun run dev              # Start development server
bun run build            # Build for production
bun run preview          # Preview production build

# Quality
bun run lint             # Check code quality
bun run lint:fix         # Fix linting issues
bun run type-check       # TypeScript type checking

# Testing
bun test                 # Run tests
bun test:coverage        # Run tests with coverage
bun test:watch           # Run tests in watch mode

# Docker
docker compose -f docker/docker-compose.yaml up -d     # Start services
docker compose -f docker/docker-compose.yaml logs      # View logs
docker compose -f docker/docker-compose.yaml down      # Stop services
```

## 🆘 Getting Help

### Documentation

- [README.md](README.md) - Project overview and setup
- [docs/API.md](docs/API.md) - API documentation
- [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) - Deployment guide
- [docs/SECURITY.md](docs/SECURITY.md) - Security guidelines

### Community

- **GitHub Issues** - Bug reports and feature requests
- **GitHub Discussions** - General questions and ideas
- **Discord/Slack** - Real-time chat with contributors

### Support

- **Email** - development@your-domain.com
- **Professional Support** - Available for enterprise users
- **Consulting** - Custom development and deployment assistance

## 📄 License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

## 🙏 Recognition

Contributors will be:

- Listed in the CHANGELOG.md for their contributions
- Mentioned in release notes for significant features
- Added to the contributors section of README.md
- Eligible for contributor benefits and recognition

### Types of Contributions Recognized

- **Code contributions** - Features, bug fixes, improvements
- **Documentation** - Writing, editing, translating
- **Testing** - Bug reports, test writing, QA
- **Design** - UI/UX improvements, graphics, branding
- **Community** - Support, mentoring, evangelism

Thank you for contributing to the Medication Reminder App! Your efforts help improve healthcare outcomes for users worldwide. 🌟