Files

9.8 KiB

Contributing Guide

Welcome Contributors!

Thank you for your interest in contributing to XPack WebUI. This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

  • Node.js 18+
  • pnpm (recommended package manager)
  • Git
  • Basic knowledge of React, Next.js 15, and TypeScript 5

Development Setup

  1. Fork the Repository

    • Click the "Fork" button on GitHub
    • Clone your fork locally:
      git clone https://github.com/xpack-ai/XPack-MCP-Market.git
      cd XPack-MCP-Market/frontend
      
  2. Set Up Development Environment

    # Install dependencies (from project root)
    pnpm install
    
    # Copy environment file
    cp .env.example .env.local
    
    # Start development server
    pnpm dev
    
  3. Create a Branch

    git checkout -b feature/your-feature-name
    # or
    git checkout -b fix/your-bug-fix
    

Development Guidelines

Code Style

We follow strict coding standards to maintain code quality:

  • TypeScript: Use strict mode, provide proper types
  • ESLint: Follow the configured rules
  • Prettier: Code is automatically formatted
  • File Naming: Use kebab-case for files, PascalCase for components

Component Structure

// Good component structure
import React from 'react'
import { useTranslation } from '@/shared/lib/useTranslation'
import type { ComponentProps } from './types'

interface MyComponentProps extends ComponentProps {
  title: string
  onAction: () => void
}

export function MyComponent({ title, onAction, ...props }: MyComponentProps) {
  const { t } = useTranslation()

  return (
    <div className="p-4" {...props}>
      <h2 className="text-xl font-semibold">{title}</h2>
      <button onClick={onAction} className="btn-primary">
        {t('Action')}
      </button>
    </div>
  )
}

State Management

  • Use Zustand for global state
  • Use React hooks for local component state
  • Keep state as close to where it's used as possible
// Global state example
import { create } from "zustand";

interface FeatureStore {
  data: FeatureData[];
  loading: boolean;
  fetchData: () => Promise<void>;
}

export const useFeatureStore = create<FeatureStore>((set, get) => ({
  data: [],
  loading: false,
  fetchData: async () => {
    set({ loading: true });
    try {
      const data = await fetchFeatureData();
      set({ data, loading: false });
    } catch (error) {
      set({ loading: false });
      throw error;
    }
  },
}));

API Integration

  • Use the existing API service pattern
  • Handle errors appropriately
  • Provide loading states
// API service example using fetchAPI
import { fetchAPI } from "@/shared/rpc/common-function";
import { fetchAdminAPI } from "@/rpc/admin-api";

// Public API call
export async function fetchServices(): Promise<ServiceData[]> {
  const response = await fetchAPI("/api/web/mcp_services");
  return response.data;
}

// Admin API call
export async function getMCPServiceList(
  params: GetMCPServiceListParams
): Promise<MCPServiceListApiResponse> {
  const queryParams = new URLSearchParams({
    page: params.page.toString(),
    page_size: params.page_size.toString(),
    ...(params.search && { search: params.search }),
    ...(params.status && { status: params.status }),
  });

  return await fetchAdminAPI<MCPService[]>(
    `/api/mcp/service/list?${queryParams.toString()}`,
    { method: "GET" }
  );
}

Internationalization

  • Add translations for all user-facing text
  • Use the translation hook consistently
  • Update both English and Chinese translations
// Component with i18n
import { useTranslation } from '@/shared/lib/useTranslation'

function MyComponent() {
  const { t } = useTranslation()

  return (
    <div>
      <h1>{t('Welcome')}</h1>
      <p>{t('This is a description')}</p>
    </div>
  )
}
// public/locales/en/translation.json
{
  "Welcome": "Welcome",
  "This is a description": "This is a description"
}

// public/locales/zh-CN/translation.json
{
  "Welcome": "欢迎",
  "This is a description": "这是一个描述"
}

Types of Contributions

🐛 Bug Fixes

  1. Identify the Bug

    • Check if the issue already exists
    • Reproduce the bug locally
    • Understand the root cause
  2. Fix the Bug

    • Write a minimal fix
    • Add tests if applicable
    • Ensure no regression
  3. Test the Fix

    • Test manually in browser
    • Run automated tests
    • Check different scenarios

✨ New Features

  1. Feature Planning

    • Discuss the feature in issues first
    • Consider the user experience
    • Plan the implementation approach
  2. Implementation

    • Break down into smaller tasks
    • Follow existing patterns
    • Add proper TypeScript types
  3. Documentation

    • Update relevant documentation
    • Add code comments where needed
    • Update translation files

📚 Documentation

  • Fix typos and grammar
  • Add missing documentation
  • Improve existing explanations
  • Add code examples

🎨 UI/UX Improvements

  • Follow the existing design system
  • Use NextUI components when possible
  • Ensure responsive design
  • Test on different screen sizes

🌐 Translations

  • Add support for new languages
  • Fix translation errors
  • Improve translation quality

Pull Request Process

Before Submitting

  1. Code Quality

    # Run linting
    pnpm lint
    
    # Check TypeScript
    pnpm type-check
    
    # Run tests
    pnpm test
    
    # Build check
    pnpm build
    
  2. Test Your Changes

    • Test in development environment
    • Check different browsers
    • Verify responsive design
    • Test with different data scenarios
  3. Update Documentation

    • Update README if needed
    • Add/update code comments
    • Update translation files

Submitting the PR

  1. Commit Messages Use conventional commit format:

    feat: add user profile management
    fix: resolve navigation menu bug
    docs: update API documentation
    style: improve button styling
    refactor: simplify authentication logic
    test: add unit tests for services
    
  2. PR Title and Description

    • Clear, descriptive title
    • Explain what changes were made
    • Reference related issues
    • Include screenshots for UI changes
  3. PR Template

    ## Description
    
    Brief description of changes
    
    ## Type of Change
    
    - [ ] Bug fix
    - [ ] New feature
    - [ ] Documentation update
    - [ ] Style/UI improvement
    
    ## Testing
    
    - [ ] Tested locally
    - [ ] Added/updated tests
    - [ ] Checked responsive design
    
    ## Screenshots (if applicable)
    
    Add screenshots here
    
    ## Related Issues
    
    Fixes #123
    

Review Process

  1. Automated Checks

    • All CI checks must pass
    • Code coverage requirements
    • Build must succeed
  2. Code Review

    • Maintainers will review within 48 hours
    • Address feedback promptly
    • Be open to suggestions
  3. Approval and Merge

    • At least one approval required
    • All conversations resolved
    • Maintainer will merge

Testing

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Type checking
pnpm type-check

# Linting
pnpm lint

# Build check
pnpm build

Writing Tests

// Component test example
import { render, screen, fireEvent } from '@testing-library/react'
import { MyComponent } from './MyComponent'

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent title="Test Title" onAction={jest.fn()} />)
    expect(screen.getByText('Test Title')).toBeInTheDocument()
  })

  it('calls onAction when button is clicked', () => {
    const mockAction = jest.fn()
    render(<MyComponent title="Test" onAction={mockAction} />)

    fireEvent.click(screen.getByRole('button'))
    expect(mockAction).toHaveBeenCalledTimes(1)
  })
})

Test Coverage

  • Aim for >80% test coverage
  • Focus on critical functionality
  • Test edge cases and error scenarios

Code Review Guidelines

For Contributors

  • Be responsive to feedback
  • Ask questions if unclear
  • Make requested changes promptly
  • Keep discussions professional

For Reviewers

  • Be constructive and helpful
  • Explain the reasoning behind suggestions
  • Approve when ready, request changes when needed
  • Focus on code quality and user experience

Community Guidelines

Communication

  • Be respectful and inclusive
  • Help newcomers get started
  • Share knowledge and best practices
  • Use GitHub Discussions for questions

Issue Reporting

  1. Search Existing Issues

    • Check if the issue already exists
    • Add to existing discussion if relevant
  2. Provide Details

    • Clear description of the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment information
  3. Use Issue Templates

    • Bug report template
    • Feature request template
    • Question template

Feature Requests

  1. Describe the Problem

    • What problem does this solve?
    • Who would benefit from this feature?
  2. Propose a Solution

    • How should it work?
    • What should the user experience be?
  3. Consider Alternatives

    • Are there other ways to solve this?
    • How do other tools handle this?

Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • Release notes for significant contributions
  • Project documentation
  • Community discussions

Getting Help

  • GitHub Discussions: For questions and general discussion
  • GitHub Issues: For bug reports and feature requests
  • Code Comments: For implementation questions
  • Documentation: Check existing docs first

License

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


Thank you for contributing to XPack WebUI! Your contributions help make this project better for everyone.