aethex-studio/CONTRIBUTING.md

Contributing to AeThex Studio

Thank you for your interest in contributing to AeThex Studio! We welcome contributions from the community.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/aethex-studio.git
   cd aethex-studio
   

3. Install dependencies:

   npm install
   

4. Create a branch for your feature:

   git checkout -b feature/my-amazing-feature
   

Development Workflow

Running the Development Server

npm run dev

Visit http://localhost:3000 to see your changes in real-time.

Code Style

• We use TypeScript for type safety
• Follow existing code patterns and conventions
• Use ESLint to check your code:

  npm run lint
  

Testing

Before submitting a PR, ensure all tests pass:

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Check test coverage
npm run test:coverage

Writing Tests

• Place tests in src/components/__tests__/ or src/hooks/__tests__/
• Use descriptive test names
• Test both success and error cases
• Example:

  describe('MyComponent', () => {
    it('should render correctly', () => {
      // Your test here
    });
  
    it('should handle errors gracefully', () => {
      // Your test here
    });
  });
  

Types of Contributions

🐛 Bug Fixes

1. Check if the bug is already reported in Issues
2. If not, create a new issue with:
   • Clear description
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots (if applicable)
3. Create a fix and submit a PR

✨ New Features

1. Discuss first - Open an issue to discuss the feature before implementing
2. Wait for approval from maintainers
3. Implement the feature
4. Add tests
5. Update documentation
6. Submit a PR

📝 Documentation

• Fix typos
• Improve clarity
• Add examples
• Update outdated information

🎨 UI/UX Improvements

• Follow the existing design system
• Ensure responsive design (mobile + desktop)
• Test accessibility
• Add screenshots to PR

Pull Request Process

Before Submitting

• Code builds without errors (npm run build)
• All tests pass (npm test)
• Linting passes (npm run lint)
• Code is well-commented
• Documentation is updated
• Commit messages are clear and descriptive

Commit Messages

Use clear, descriptive commit messages:

# Good
git commit -m "Add drag-and-drop support for file tree"
git commit -m "Fix search highlighting bug in SearchPanel"

# Bad
git commit -m "Update stuff"
git commit -m "Fix bug"

Submitting

1. Push your branch to your fork
2. Open a PR against the main branch
3. Fill out the PR template
4. Wait for review

PR Template

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing
Describe how you tested this change

## Screenshots (if applicable)
Add screenshots here

## Checklist
- [ ] Tests pass
- [ ] Linting passes
- [ ] Documentation updated
- [ ] Responsive on mobile

Code Organization

File Structure

src/
├── components/          # React components
│   ├── ui/             # Reusable UI components
│   ├── __tests__/      # Component tests
│   └── ComponentName.tsx
├── hooks/              # Custom React hooks
│   ├── __tests__/      # Hook tests
│   └── use-hook-name.ts
├── lib/                # Utilities and helpers
│   └── helpers.ts
└── App.tsx             # Main application

Naming Conventions

• Components: PascalCase (FileTree.tsx, AIChat.tsx)
• Hooks: camelCase with use prefix (use-theme.ts, use-keyboard-shortcuts.ts)
• Utilities: camelCase (helpers.ts, validators.ts)
• Tests: Match component name with .test.tsx or .test.ts

Adding New Features

Adding a New Template

1. Edit src/lib/templates.ts
2. Add your template to the templates array:

   {
     id: 'your-template-id',
     name: 'Template Name',
     description: 'Brief description',
     category: 'beginner' | 'gameplay' | 'ui' | 'tools' | 'advanced',
     code: `-- Your Lua code here`,
   }
   

Adding a New Component

1. Create the component file in src/components/
2. Write the component with TypeScript types
3. Add tests in src/components/__tests__/
4. Export from the component file
5. Import and use in App.tsx or parent component

Adding a Keyboard Shortcut

1. Edit src/App.tsx
2. Add to the useKeyboardShortcuts array:

   {
     key: 'x',
     meta: true,
     ctrl: true,
     handler: () => {
       // Your action here
     },
     description: 'Description of shortcut',
   }
   

3. Update README.md keyboard shortcuts table

Performance Guidelines

• Use React.lazy() for code splitting
• Memoize expensive computations with useMemo()
• Use useCallback() for function props
• Optimize re-renders with React.memo()
• Lazy load images and heavy components

Accessibility Guidelines

• Add proper ARIA labels
• Ensure keyboard navigation works
• Test with screen readers
• Maintain good color contrast
• Add focus indicators

Questions?

• Open an issue for questions
• Join our community discussions
• Check existing issues and PRs

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Give constructive feedback
• Focus on the code, not the person

License

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

---

Thank you for contributing to AeThex Studio! 🎉