​

Contribution Guidelines

​

Code of Conduct

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community and users
• Showing empathy towards other community members

​

Getting Started

​

Repository Structure

mood-mnky/
├── apps/               # Frontend and backend applications
│   ├── api/            # Backend API services
│   ├── web/            # Main web application
│   └── mobile/         # Mobile application 
├── packages/           # Shared packages and libraries
│   ├── ui/             # Shared UI components
│   ├── utils/          # Utility functions
│   └── api-client/     # API client libraries
├── services/           # Microservices
│   ├── auth/           # Authentication service
│   ├── fragrance/      # Fragrance recommendation service
│   └── analytics/      # Analytics service
├── docs/               # Documentation (MNKY MIND)
└── tools/              # Development and build tools

​

Setting Up Your Development Environment

1. Clone the repository:
   Copy

   git clone https://github.com/mood-mnky/mood-mnky.git
   cd mood-mnky
   

2. Install dependencies:
   Copy

   npm install
   

3. Set up environment variables: Copy the example environment file and update with your local configuration:
   Copy

   cp .env.example .env.local
   

4. Start development server:
   Copy

   npm run dev
   

​

Development Workflow

​

1. Creating a New Feature

git checkout -b feature/your-feature-name

npm run test
npm run lint

​

2. Submitting a Pull Request

git push origin feature/your-feature-name

​

Coding Standards

​

TypeScript Style Guide

import { useState, useEffect } from 'react'
import type { User } from '@/types'
import { fetchUserData } from '@/lib/api'

interface UserProfileProps {
  userId: string
  showDetails?: boolean
}

export function UserProfile({ userId, showDetails = false }: UserProfileProps) {
  const [user, setUser] = useState<User | null>(null)
  const [isLoading, setIsLoading] = useState<boolean>(true)
  const [hasError, setHasError] = useState<boolean>(false)

  useEffect(() => {
    async function loadUser() {
      try {
        setIsLoading(true)
        const userData = await fetchUserData(userId)
        setUser(userData)
      } catch (error) {
        console.error('Failed to fetch user:', error)
        setHasError(true)
      } finally {
        setIsLoading(false)
      }
    }

    loadUser()
  }, [userId])

  if (isLoading) return <div>Loading...</div>
  if (hasError) return <div>Error loading user profile</div>
  if (!user) return null

  return (
    <div className="user-profile">
      <h2>{user.name}</h2>
      {showDetails && (
        <div className="user-details">
          <p>Email: {user.email}</p>
          <p>Member since: {new Date(user.createdAt).toLocaleDateString()}</p>
        </div>
      )}
    </div>
  )
}

​

Key Principles

1. Type Safety: Always use proper TypeScript types and interfaces
2. Function Components: Use function components with hooks instead of class components
3. Named Exports: Prefer named exports over default exports
4. Descriptive Naming: Use clear, descriptive names for variables, functions, and components
5. State Management: Use appropriate state management based on complexity
6. Error Handling: Implement comprehensive error handling
7. Async/Await: Use async/await for asynchronous operations
8. Comments: Add comments for complex logic, but aim for self-documenting code

​

Commit Message Convention

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

[optional body]

[optional footer(s)]

​

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Changes that don’t affect code functionality (whitespace, formatting, etc.)
• refactor: Code changes that neither fix bugs nor add features
• perf: Performance improvements
• test: Adding or modifying tests
• chore: Changes to build process, tools, etc.

​

Example Commit Messages

feat(auth): add social login options for Google and Apple

Implements OAuth2 authentication flow for Google and Apple accounts.
Includes:
- New OAuth providers configuration
- UI components for social login buttons
- Integration tests

Closes #123

fix(api): correct error handling in product search endpoint

Properly handle and format errors when search parameters are invalid.

Fixes #456

​

Testing Guidelines

• Jest: For unit and integration tests
• React Testing Library: For component tests
• Cypress: For end-to-end tests

​

Testing Requirements

1. Unit Tests: Required for all utility functions and custom hooks
2. Component Tests: Required for all UI components
3. Integration Tests: Required for complex features and workflows
4. End-to-End Tests: Required for critical user journeys

// utils/formatters.test.ts
import { formatCurrency, formatDate, truncateText } from './formatters'

describe('formatCurrency', () => {
  it('formats USD correctly', () => {
    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56')
  })
  
  it('handles zero values', () => {
    expect(formatCurrency(0, 'USD')).toBe('$0.00')
  })
})

describe('truncateText', () => {
  it('truncates text longer than maxLength', () => {
    expect(truncateText('Hello world', 5)).toBe('Hello...')
  })
  
  it('does not truncate text shorter than maxLength', () => {
    expect(truncateText('Hello', 10)).toBe('Hello')
  })
})

​

Documentation

​

Code Documentation

• Use JSDoc comments for functions, classes, and interfaces
• Document parameters, return values, and thrown exceptions
• Include examples for complex functions

/**
 * Generates a personalized fragrance recommendation based on user preferences.
 * 
 * @param userId - The ID of the user to generate recommendations for
 * @param options - Configuration options for the recommendation algorithm
 * @param options.limit - Maximum number of recommendations to return (default: 5)
 * @param options.includeDetails - Whether to include detailed fragrance information (default: false)
 * @returns Promise resolving to an array of recommended fragrance objects
 * @throws {AuthError} If the user is not authenticated
 * @throws {ApiError} If there's an error fetching user preferences or fragrance data
 * 
 * @example
 * ```ts
 * // Get basic recommendations
 * const recommendations = await getFragranceRecommendations('user123')
 * 
 * // Get detailed recommendations with limit
 * const detailedRecs = await getFragranceRecommendations('user123', { 
 *   limit: 3, 
 *   includeDetails: true 
 * })
 * ```
 */
export async function getFragranceRecommendations(
  userId: string,
  options: RecommendationOptions = {}
): Promise<FragranceRecommendation[]> {
  // Implementation
}

​

Product Documentation

1. Update relevant documentation in the /docs directory
2. Add or update examples and usage instructions
3. Include screenshots or videos for UI changes

​

Review Process

1. Automated Checks: Linting, type checking, and tests
2. Code Review: Review by at least one team member
3. UX Review: For UI changes
4. Security Review: For authentication, data handling, or API changes
5. Performance Review: For changes that might impact performance

​

Continuous Integration and Deployment

1. Build Verification: Ensures the project builds successfully
2. Automated Tests: Runs unit, integration, and e2e tests
3. Linting and Type Checking: Enforces code style and type safety
4. Preview Deployments: Creates temporary deployment for PR review
5. Production Deployment: Automated deployment to production after merge

​

Getting Help

• Developer Discord: Join our developer channel for real-time help
• GitHub Discussions: Post questions or suggestions
• Issues: Review existing issues or create a new one
• Documentation: Consult our comprehensive documentation

​

Recognition

• Contributors are listed in our GitHub repository
• Significant contributions are highlighted in release notes
• Regular contributors may be invited to join the core team