# 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:
```bash
git clone https://github.com/xpack-ai/XPack-MCP-Market.git
cd XPack-MCP-Market/frontend
```
2. **Set Up Development Environment**
```bash
# Install dependencies (from project root)
pnpm install
# Copy environment file
cp .env.example .env.local
# Start development server
pnpm dev
```
3. **Create a Branch**
```bash
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
```typescript
// 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 (
{title}
)
}
```
### 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
```typescript
// Global state example
import { create } from "zustand";
interface FeatureStore {
data: FeatureData[];
loading: boolean;
fetchData: () => Promise;
}
export const useFeatureStore = create((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
```typescript
// 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 {
const response = await fetchAPI("/api/web/mcp_services");
return response.data;
}
// Admin API call
export async function getMCPServiceList(
params: GetMCPServiceListParams
): Promise {
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(
`/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
```typescript
// Component with i18n
import { useTranslation } from '@/shared/lib/useTranslation'
function MyComponent() {
const { t } = useTranslation()
return (
{t('Welcome')}
{t('This is a description')}
)
}
```
```json
// 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**
```bash
# 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**
```markdown
## 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
```bash
# 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
```typescript
// Component test example
import { render, screen, fireEvent } from '@testing-library/react'
import { MyComponent } from './MyComponent'
describe('MyComponent', () => {
it('renders correctly', () => {
render()
expect(screen.getByText('Test Title')).toBeInTheDocument()
})
it('calls onAction when button is clicked', () => {
const mockAction = jest.fn()
render()
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.