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.

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

# 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

# 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

# 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

# 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

# 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

// 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

// 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

/* 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

// 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

// 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

# 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:

// 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 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:

• 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

# 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 - Project overview and setup
• docs/API.md - API documentation
• docs/DEPLOYMENT.md - Deployment guide
• 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. 🌟