Contributing Guide

Contributing Overview

MegaVault is an open-source project that welcomes contributions from developers of all skill levels. Whether you're fixing bugs, adding features, improving documentation, or helping with translations, your contributions are valuable and appreciated.

Getting Started

Before making your first contribution, familiarize yourself with the codebase, development environment, and contribution process.

Prerequisites

• GitHub Account: Required for forking and submitting pull requests
• Development Environment: Follow the development setup guide
• Understanding of Git: Basic knowledge of Git workflows
• Familiarity with Tech Stack: Next.js, React, TypeScript, Tailwind CSS

Contribution Workflow

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/S3-MegaVault.git
cd S3-MegaVault

# Add the original repository as upstream
git remote add upstream https://github.com/iotserver24/S3-MegaVault.git

# Update your local main branch
git checkout main
git pull upstream main

# Create and switch to a new feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

# Make your changes
# Run tests to ensure everything works
npm run test

# Run linting to check code quality
npm run lint

# Format code
npm run format

# Stage your changes
git add .

# Commit with descriptive message
git commit -m "feat: add user profile management feature"

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

Types of Contributions

Development Workflow

Follow this workflow to ensure smooth collaboration and maintain code quality.

Branch Naming

• Features: feature/descriptive-name
• Bug fixes: fix/issue-description
• Documentation: docs/section-name
• Refactoring: refactor/component-name
• Tests: test/feature-name

Commit Messages

Use conventional commits format for clear and consistent commit history:

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

# Types
feat: new feature
fix: bug fix
docs: documentation changes
style: formatting, missing semicolons, etc.
refactor: code refactoring
test: adding or updating tests
chore: maintenance tasks

# Examples
feat(auth): add two-factor authentication
fix(upload): resolve file corruption issue
docs(api): update authentication endpoints
style(dashboard): improve responsive layout
refactor(storage): optimize file retrieval logic
test(auth): add unit tests for login flow
chore(deps): update dependencies to latest versions

Development Process

1. Create Issue: Create or find an existing issue for your contribution
2. Discussion: Discuss the approach and implementation details
3. Development: Implement changes following coding standards
4. Testing: Write tests and ensure all tests pass
5. Documentation: Update documentation as needed
6. Review: Submit pull request for code review

Coding Standards

Maintain consistent code quality and style across the project by following these standards.

TypeScript Guidelines

• Strict Mode: Always use strict TypeScript configuration
• Type Definitions: Provide explicit types for function parameters and return values
• Interfaces: Use interfaces for object structures
• Generics: Use generics for reusable components and functions
• No Any: Avoid using 'any' type; use specific types or unions

// Good: Explicit types and interfaces
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

async function getUser(id: string): Promise<User | null> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    console.error('Failed to fetch user:', error);
    return null;
  }
}

// Good: Generic components
interface ButtonProps<T = HTMLButtonElement> {
  variant: 'primary' | 'secondary';
  onClick: (event: React.MouseEvent<T>) => void;
  children: React.ReactNode;
}

// Avoid: Using any
// function handleData(data: any): any { ... }

React Component Guidelines

• Functional Components: Use functional components with hooks
• Props Interface: Define props interface for each component
• Default Props: Use default parameters instead of defaultProps
• Error Boundaries: Implement error boundaries for error handling
• Accessibility: Include proper ARIA attributes and semantic HTML

Code Formatting

• Prettier: Use Prettier for consistent code formatting
• ESLint: Follow ESLint rules for code quality
• Import Order: Group imports logically (external, internal, relative)
• Naming Conventions: Follow established naming patterns

// 1. React and external libraries
import React, { useState, useEffect } from 'react';
import { useRouter } from 'next/router';
import { z } from 'zod';

// 2. Internal utilities and hooks
import { cn } from '@/lib/utils';
import { useAuth } from '@/hooks/useAuth';

// 3. Components
import { Button } from '@/components/ui/Button';
import { FileList } from '@/components/features/files/FileList';

// 4. Types
import type { User, FileMetadata } from '@/types';

// 5. Relative imports
import './ComponentName.css';

Pull Request Process

Follow this process to ensure your pull requests are reviewed and merged efficiently.

Before Submitting

• Test Locally: Ensure all tests pass and the application works correctly
• Check Linting: Fix any linting errors or warnings
• Update Documentation: Add or update relevant documentation
• Rebase: Rebase your branch on the latest main branch
• Clean History: Squash or clean up commit history if needed

Pull Request Template

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which 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
- [ ] All existing tests pass

## Screenshots (if applicable)
Add screenshots to help explain your changes.

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings

Review Process

1. Automated Checks: CI/CD pipeline runs tests and linting
2. Code Review: Maintainers review code quality and functionality
3. Feedback: Address any review comments or suggestions
4. Approval: Get approval from required reviewers
5. Merge: Maintainer merges the pull request

Issue Reporting

Help improve MegaVault by reporting bugs, requesting features, or asking questions.

Bug Reports

Feature Requests

• Use Case: Explain the problem you're trying to solve
• Proposed Solution: Describe your ideal solution
• Alternatives: Consider alternative approaches
• Implementation: Are you willing to implement the feature?

Security Issues

Documentation

Good documentation is crucial for project success. Contribute by improving existing docs or adding new ones.

Documentation Types

• User Documentation: Installation, usage, and troubleshooting guides
• Developer Documentation: API references, architecture, and contributing guides
• Code Comments: Inline documentation for complex code
• README Files: Project overview and quick start information

Writing Guidelines

• Clear and Concise: Use simple language and short sentences
• Examples: Include practical examples and code snippets
• Structure: Use headings, lists, and tables for organization
• Accuracy: Ensure all information is current and correct
• Accessibility: Write for users of all skill levels

Documentation Standards

• Markdown: Use Markdown for all documentation files
• Code Blocks: Use syntax highlighting for code examples
• Links: Use relative links for internal documentation
• Images: Optimize images and provide alt text
• Table of Contents: Include TOC for longer documents

Community Guidelines

MegaVault is committed to providing a welcoming and inclusive environment for all contributors.

Code of Conduct

• Be Respectful: Treat all community members with respect and kindness
• Be Inclusive: Welcome people of all backgrounds and skill levels
• Be Constructive: Provide helpful feedback and suggestions
• Be Patient: Remember that everyone is learning and improving
• Be Professional: Keep discussions focused and productive

Communication Channels

Getting Help

• Documentation: Check existing documentation first
• Search Issues: Look for similar questions or problems
• Ask Questions: Use GitHub Discussions for questions
• Provide Context: Include relevant details when asking for help
• Be Patient: Allow time for community members to respond