# Contributing to MyPowerPost

Thank you for considering contributing to MyPowerPost! This document provides guidelines and instructions for contributing.

## 🤝 Code of Conduct

- Be respectful and inclusive
- Welcome newcomers
- Accept constructive criticism
- Focus on what's best for the community

## 🐛 Reporting Bugs

Before creating a bug report, please check existing issues. When creating a bug report, include:

- **Description**: Clear description of the bug
- **Steps to Reproduce**: Step-by-step instructions
- **Expected Behavior**: What should happen
- **Actual Behavior**: What actually happens
- **Environment**: OS, browser, Node version
- **Screenshots**: If applicable

### Bug Report Template

```markdown
## Description
Brief description of the bug

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

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Environment
- OS: [e.g., Windows 11]
- Browser: [e.g., Chrome 120]
- Node Version: [e.g., 18.17.0]

## Screenshots
If applicable
```

## 💡 Suggesting Features

Feature requests are welcome! Please include:

- **Use Case**: Why is this feature needed?
- **Proposed Solution**: How should it work?
- **Alternatives**: Other solutions you've considered
- **Additional Context**: Any other relevant information

## 🔧 Development Process

### Setting Up Development Environment

1. **Fork the repository**
```bash
gh repo fork yourusername/my-power-post-pwa
```

2. **Clone your fork**
```bash
git clone https://github.com/YOUR_USERNAME/my-power-post-pwa.git
cd my-power-post-pwa
```

3. **Add upstream remote**
```bash
git remote add upstream https://github.com/ORIGINAL_OWNER/my-power-post-pwa.git
```

4. **Install dependencies**
```bash
npm install
```

5. **Set up environment**
```bash
cp .env.example .env
# Edit .env with your configuration
```

6. **Set up database**
```bash
npx prisma generate
npx prisma db push
```

### Making Changes

1. **Create a branch**
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

Branch naming convention:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation changes
- `refactor/` - Code refactoring
- `test/` - Adding tests
- `chore/` - Maintenance tasks

2. **Make your changes**
- Write clean, readable code
- Follow existing code style
- Add comments for complex logic
- Update relevant documentation

3. **Test your changes**
```bash
npm run lint          # Check for linting errors
npx tsc --noEmit     # Type check
npm run build        # Ensure build works
```

4. **Commit your changes**
```bash
git add .
git commit -m "feat: add user profile editing feature"
```

Commit message convention:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `style:` - Formatting changes
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance

5. **Push to your fork**
```bash
git push origin feature/your-feature-name
```

6. **Create Pull Request**
- Go to your fork on GitHub
- Click "New Pull Request"
- Fill in the PR template
- Link related issues

## 📝 Pull Request Guidelines

### PR Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review of code performed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings or errors
- [ ] Changes tested locally
- [ ] Related issues linked

### PR Description Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
How has this been tested?

## Screenshots (if applicable)
Before/after screenshots

## Related Issues
Closes #123
```

## 🎨 Coding Standards

### TypeScript

```typescript
// ✅ Good
interface UserProfile {
  id: string
  name: string
  email: string
}

export function getUserProfile(userId: string): Promise<UserProfile> {
  // Implementation
}

// ❌ Bad
export function getUser(id: any): any {
  // Implementation
}
```

### React Components

```typescript
// ✅ Good - Functional component with TypeScript
interface ButtonProps {
  label: string
  onClick: () => void
  variant?: 'primary' | 'secondary'
}

export function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button onClick={onClick} className={`btn-${variant}`}>
      {label}
    </button>
  )
}

// ❌ Bad - No types, unclear naming
export function Btn(props) {
  return <button onClick={props.fn}>{props.txt}</button>
}
```

### File Naming

- Components: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
- Utilities: `kebab-case.ts` (e.g., `format-date.ts`)
- Server Actions: `kebab-case-actions.ts` (e.g., `post-actions.ts`)
- Types: `kebab-case.ts` (e.g., `post-types.ts`)

### Code Organization

```typescript
// Order of elements in a component file:
// 1. Imports
import { useState } from 'react'
import { Button } from '@/components/ui/button'

// 2. Types/Interfaces
interface Props {
  title: string
}

// 3. Constants
const DEFAULT_TITLE = 'Hello'

// 4. Component
export function MyComponent({ title }: Props) {
  // 4a. Hooks
  const [count, setCount] = useState(0)
  
  // 4b. Handlers
  const handleClick = () => {
    setCount(count + 1)
  }
  
  // 4c. Render
  return (
    <div>
      <h1>{title}</h1>
      <Button onClick={handleClick}>Count: {count}</Button>
    </div>
  )
}
```

## 🧪 Testing

Currently, the project doesn't have comprehensive tests. Contributing tests would be valuable!

### When Tests Are Added

```bash
# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run E2E tests
npm run test:e2e
```

## 📚 Documentation

When adding features:

1. Update relevant documentation
2. Add JSDoc comments to functions
3. Update README.md if needed
4. Add examples for new features

Example:
```typescript
/**
 * Creates a new post in the database
 * 
 * @param content - The post content (max 500 characters)
 * @param authorId - The ID of the post author
 * @param options - Additional post options
 * @returns The created post with author information
 * 
 * @example
 * ```typescript
 * const post = await createPost(
 *   "Hello world!",
 *   "user_123",
 *   { privacy: "PUBLIC" }
 * )
 * ```
 */
export async function createPost(
  content: string,
  authorId: string,
  options?: PostOptions
): Promise<Post> {
  // Implementation
}
```

## 🔍 Code Review Process

All PRs require review before merging:

1. Automated checks must pass
2. At least one maintainer approval
3. No unresolved conversations
4. Branch up to date with main

Reviewers will check:
- Code quality and style
- Test coverage
- Documentation
- Performance implications
- Security concerns

## 🚀 Release Process

Maintainers handle releases:

1. Version bump following [Semantic Versioning](https://semver.org/)
2. Update CHANGELOG.md
3. Create release tag
4. Deploy to production

## 📞 Getting Help

- 💬 Discord: [Join our community](#)
- 📧 Email: dev@mypowerpost.com
- 📖 Documentation: See README.md
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/my-power-post-pwa/issues)

## 🎉 Recognition

Contributors will be:
- Listed in CONTRIBUTORS.md
- Mentioned in release notes
- Added to our Hall of Fame

Thank you for contributing to MyPowerPost! 🙏