mirror of https://github.com/johndoe6345789/metabuilder.git synced 2026-04-24 22:04:56 +00:00

Files

JohnDoe6345789 b2379aee23 feat: add .actrc and .secrets.example files, enhance documentation, and implement pre-push git hook for workflow validation

2025-12-25 15:58:02 +00:00

5.9 KiB

Raw Blame History

Contributing Guide

How to contribute to MetaBuilder development.

Getting Started

Prerequisites

Node.js 18+
Git
npm or yarn

Setting Up Development Environment

Clone Repository
```
git clone <repo>
cd metabuilder
```
Install Dependencies
```
npm install
```
Set Up Database
```
npm run db:generate
npm run db:push
```
Start Development Server
```
npm run dev
```
Run Tests
```
npm run test:e2e
npm run lint
```

Code Style

TypeScript/React Conventions

Component Size - Keep components under 150 lines of code
Naming - Use PascalCase for components, camelCase for functions
Imports - Use absolute imports with @/ prefix
Props - Define prop interfaces, use destructuring

Example:

// ✅ Good
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

export function Button({ label, onClick, disabled }: ButtonProps) {
  return <button onClick={onClick} disabled={disabled}>{label}</button>;
}

// ❌ Bad - No props interface, too many lines
export function Button(props: any) {
  // ... 200 lines of code
}

Styling

Use Tailwind utility classes exclusively
No CSS-in-JS or inline styles
Follow theme from src/index.css

// ✅ Good
<button className="px-4 py-2 bg-blue-500 text-white rounded">
  Click me
</button>

// ❌ Bad
<button style={{ padding: "8px 16px", backgroundColor: "blue" }}>
  Click me
</button>

Hooks & State Management

Use React hooks (useState, useEffect, useContext)
Keep hooks in separate hook files in src/hooks/
Export from src/hooks/index.ts for easy importing

Testing

Running Tests

# Unit tests
npm run test:unit:watch

# E2E tests
npm run test:e2e

# All tests
npm run test:all

Writing Tests

Unit Tests - Test individual functions in isolation

it('calculates total correctly', () => {
  expect(calculateTotal([1, 2, 3])).toBe(6);
});

E2E Tests - Test complete user flows

test('user can create and edit item', async ({ page }) => {
  await page.goto('/');
  await page.fill('[name="title"]', 'Test');
  await page.click('button[type="submit"]');
  await expect(page.locator('text=Test')).toBeVisible();
});

Coverage - Aim for 80%+ coverage on critical paths

Documentation

Adding Documentation

JSDoc Comments - Document all exported functions and interfaces

/**
 * Calculates the sum of numbers
 * @param numbers - Array of numbers to sum
 * @returns The sum of all numbers
 * @example
 * const total = sum([1, 2, 3]); // 6
 */
export function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

README Files - Keep README.md in key directories:
- /src/ - Source code overview
- /src/lib/ - Library utilities
- /src/components/ - Component library
- /packages/ - Modular packages
Architecture Docs - Document complex systems in docs/architecture/
Examples - Create .example.tsx files showing how to use components

Running Quality Checker

# Check documentation quality
./scripts/doc-quality-checker.sh /workspaces/metabuilder

# With verbose output
./scripts/doc-quality-checker.sh /workspaces/metabuilder true

Target: 80%+ quality score

Pull Request Process

Before Creating PR

Run Linter
```
npm run lint
```
Fix Issues
```
npm run lint:fix
```
Run Tests
```
npm run test:e2e
```
Update Documentation
- Add/update JSDoc comments
- Update README if needed
- Update architecture docs if design changes

PR Template

## Description
Briefly describe what this PR does.

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

## Testing
How to test these changes:
1. Step 1
2. Step 2

## Checklist
- [ ] Tests pass
- [ ] Linter passes
- [ ] Documentation updated
- [ ] No breaking changes

PR Review

Address all review comments
Keep commits clean and logical
Update PR description if scope changes
Ensure CI passes before merge

🚫 Common Mistakes

❌ Don't:

Create components larger than 150 LOC
Use CSS-in-JS or inline styles
Hardcode values that should be configurable
Skip tests for "simple" changes
Forget to update documentation
Commit without linting

✅ Do:

Keep components focused and testable
Use Tailwind CSS exclusively
Make code reusable and configurable
Test all code paths
Document as you code
Run linter before committing

🆘 Getting Help

TODO: Links below use ../docs/... from docs/CONTRIBUTING.md and resolve to docs/docs; update to correct relative paths (including security and copilot).

Architecture Questions: See docs/architecture/
API Questions: See API Development Guide TODO: E2E tests guide lives under frontends/nextjs/e2e; update this link.
Testing Questions: See E2E Tests Guide
Security Questions: See Security Guidelines

5.9 KiB Raw Blame History