Contributing to WAMR

Thank you for your interest in contributing to WAMR (WhatsApp Media Request Manager)! We welcome contributions from the community and are excited to have you on board.

Code of Conduct
How Can I Contribute?
Getting Started
Development Workflow
Coding Conventions
Commit Message Guidelines
Pull Request Process
Issue Guidelines
Testing Guidelines

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Use a clear and descriptive title
Describe the exact steps to reproduce the problem
Provide specific examples to demonstrate the steps
Describe the behavior you observed and what you expected
Include screenshots or animated GIFs if applicable
Include your environment details (OS, Node version, etc.)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

Use a clear and descriptive title
Provide a detailed description of the suggested enhancement
Explain why this enhancement would be useful
List any alternative solutions you've considered

Your First Code Contribution

Unsure where to begin? Look for issues labeled:

good first issue - Simple issues suitable for beginners
help wanted - Issues where we'd appreciate community help
documentation - Documentation improvements

Pull Requests

We actively welcome your pull requests! Here's how to contribute code:

Fork the repo and create your branch from main
If you've added code that should be tested, add tests
Ensure the test suite passes
Make sure your code lints
Issue that pull request!

Getting Started

Prerequisites

Node.js >= 20.0.0
npm >= 10.0.0
Git

Setup Development Environment

Fork and clone the repository

git clone https://github.com/YOUR_USERNAME/wamr.git
cd wamr

Install dependencies
```
npm install
```

Configure environment variables

# Backend
cd backend
cp .env.example .env
# Edit .env with your configuration

# Frontend
cd ../frontend
cp .env.example .env
# Edit .env with your configuration

Generate security keys

# JWT Secret
openssl rand -base64 32

# Encryption Key
openssl rand -hex 32

Setup database

cd backend
npm run db:generate
npm run db:migrate
npm run db:seed

Start development servers
```
cd ..
npm run dev
```

Development Workflow

Branch Strategy

main - Production-ready code
develop - Integration branch for features (if used)
feature/* - New features
bugfix/* - Bug fixes
hotfix/* - Urgent production fixes
docs/* - Documentation updates

Creating a Feature Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Making Changes

Make your changes in the feature branch
Follow the coding conventions
Write or update tests as needed
Ensure all tests pass: npm run test
Ensure code lints: npm run lint
Format your code: npm run format

Committing Changes

We follow the Conventional Commits specification:

git add .
git commit -m "feat: add new feature"

See Commit Message Guidelines for details.

Coding Conventions

TypeScript

Use TypeScript for all new code
Define types explicitly rather than using any
Use interfaces for object shapes
Use type aliases for unions and complex types
Export types from dedicated types/ files

Code Style

We use ESLint and Prettier to maintain consistent code style:

# Check linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Key conventions:

Use 2 spaces for indentation
Use single quotes for strings
Use semicolons
Use trailing commas in multi-line objects/arrays
Use arrow functions over function expressions
Use const over let when possible
Avoid var

File Organization

Group related functionality in modules
Keep files focused and under 300 lines when possible
Use index files to export public APIs
Place tests alongside the code they test

Naming Conventions

Files: kebab-case.ts
Components: PascalCase.tsx
Variables/Functions: camelCase
Constants: UPPER_SNAKE_CASE
Types/Interfaces: PascalCase
Private members: prefix with _

Backend Conventions

Use dependency injection where appropriate
Separate concerns: routes → controllers → services → repositories
Validate all inputs using Zod schemas
Use proper error handling with custom error codes
Log important events using the provided logger
Never log sensitive information (passwords, tokens, etc.)

Frontend Conventions

Use functional components with hooks
Keep components small and focused
Use custom hooks for reusable logic
Use React Query for server state
Use Zustand for client state

Follow the component structure:

// Imports
// Types
// Component
// Exports

Commit Message Guidelines

We follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, semicolons, etc.)
refactor: Code refactoring (no functional changes)
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks (dependencies, build, etc.)
ci: CI/CD changes
revert: Reverting a previous commit

Scope (Optional)

The scope should be the name of the affected module:

auth
whatsapp
media
api
ui
db
config

Examples

feat(auth): add JWT refresh token support

fix(whatsapp): resolve connection timeout issue

docs: update installation instructions

style(api): format code with prettier

refactor(media): simplify search logic

test(auth): add unit tests for login flow

chore(deps): update dependencies

Pull Request Process

Before Submitting

Update your branch with the latest main:

git checkout main
git pull origin main
git checkout your-feature-branch
git rebase main

Run all checks:

npm run lint
npm run format:check
npm run test
npm run build

Update documentation if needed
Squash commits if you have many small commits:
```
git rebase -i main
```

Submitting the PR

Push your branch:
```
git push origin your-feature-branch
```
Create the pull request on GitHub
Fill out the PR template with:
- Clear description of changes
- Reference to related issues (e.g., "Closes #123")
- Screenshots/GIFs for UI changes
- Testing notes
Request review from maintainers

PR Title Format

Use the same format as commit messages:

feat(scope): add new feature
fix(scope): resolve bug

Review Process

At least one maintainer must approve the PR
All CI checks must pass
All review comments must be addressed
Code must follow our conventions
Tests must be included for new functionality

After Approval

A maintainer will merge your PR
Your branch will be deleted automatically
You can delete your local branch:
```
git branch -d your-feature-branch
```

Issue Guidelines

Creating Issues

When creating an issue:

Search first to avoid duplicates
Use issue templates when available
Be specific and provide context
Include examples or code snippets
Add labels to categorize the issue

Issue Labels

bug - Something isn't working
enhancement - New feature or request
documentation - Documentation improvements
good first issue - Good for newcomers
help wanted - Extra attention needed
question - Further information requested
wontfix - Will not be worked on
duplicate - Duplicate of another issue
invalid - Invalid issue

Testing Guidelines

Writing Tests

Write tests for all new features
Update tests when modifying existing features
Aim for at least 80% code coverage
Write both positive and negative test cases

Test Organization

tests/
├── unit/           # Unit tests for individual functions/classes
├── integration/    # Integration tests for API endpoints
└── e2e/           # End-to-end tests for full workflows

Running Tests

# Run all tests
npm run test

# Run specific test suite
npm run test:unit
npm run test:integration
npm run test:e2e

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test -- --watch

Test Conventions

Use descriptive test names
Follow the AAA pattern (Arrange, Act, Assert)
Mock external dependencies
Clean up after tests (reset database, clear mocks)
Test edge cases and error conditions

Example Test

import { describe, it, expect, beforeEach, afterEach } from "vitest";

describe("AuthService", () => {
  let authService: AuthService;

  beforeEach(() => {
    authService = new AuthService();
  });

  afterEach(() => {
    // Cleanup
  });

  describe("login", () => {
    it("should return a token for valid credentials", async () => {
      // Arrange
      const email = "test@example.com";
      const password = "password123";

      // Act
      const result = await authService.login(email, password);

      // Assert
      expect(result).toHaveProperty("token");
      expect(result.token).toBeTruthy();
    });

    it("should throw error for invalid credentials", async () => {
      // Arrange
      const email = "test@example.com";
      const password = "wrongpassword";

      // Act & Assert
      await expect(authService.login(email, password)).rejects.toThrow(
        "Invalid credentials"
      );
    });
  });
});

Documentation

Code Documentation

Document complex logic with comments
Use JSDoc for public APIs
Keep comments up to date with code changes
Explain "why" not "what" in comments

README Updates

Update README.md when:

Adding new features
Changing setup/installation process
Modifying configuration options
Adding new dependencies

API Documentation

Update API documentation when:

Adding new endpoints
Changing request/response formats
Modifying authentication requirements
Adding new query parameters

Questions?

Check the README for basic information
Review existing issues
Ask questions in discussions
Reach out to maintainers if needed

License

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

Thank you for contributing to WAMR! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History