world-component/CONTRIBUTING.md

Contributing to World Component

Thank you for your interest in contributing to the World Component project! This document provides guidelines and information for contributors.

Table of Contents

• Getting Started
• Development Setup
• Coding Standards
• Architecture Guidelines
• Testing
• Pull Request Process
• Code Review Guidelines

Getting Started

Prerequisites

• Node.js >= 16.0.0
• npm >= 8.0.0
• Git

Development Setup

1. Fork the repository

   git clone https://github.com/yourusername/world-component.git
   cd world-component
   

2. Install dependencies

   npm install
   

3. Start development server

   npm run dev
   

4. Run type checking

   npm run type-check
   

Coding Standards

TypeScript Guidelines

• Use strict TypeScript configuration
• Provide comprehensive type definitions
• Use interfaces for object shapes
• Prefer const over let when possible
• Use meaningful variable and function names

Vue Component Guidelines

• Use Vue 3 Composition API or Class-based components with vue-facing-decorator
• Keep components focused and single-purpose
• Use proper prop validation
• Implement proper lifecycle management
• Use scoped styles when possible

Three.js Guidelines

• Follow Three.js best practices for performance
• Dispose of resources properly (geometries, materials, textures)
• Use object pooling for frequently created/destroyed objects
• Implement proper cleanup in component unmount

Documentation Standards

• Document all public methods and classes
• Include JSDoc comments for complex functions
• Provide usage examples in documentation
• Update README.md for significant changes

Code Style

• Follow PEP 8 equivalent for TypeScript (80 character line limit)
• Use meaningful variable names
• Add comments for complex logic
• Keep methods under 80 lines when possible
• Use consistent indentation (2 spaces)

Architecture Guidelines

System Design

• Keep systems modular and focused
• Use dependency injection where appropriate
• Implement proper error handling
• Follow the single responsibility principle

File Organization

src/
├── systems/           # Core rendering systems
│   ├── Controls.ts    # Camera controls
│   ├── Loop.ts        # Animation loop
│   ├── Renderer.ts    # WebGL renderer
│   └── Resizer.ts     # Responsive resizing
├── components/
│   └── objects/       # 3D objects
├── types/             # TypeScript definitions
└── utils/             # Utility functions

Adding New Systems

1. Create a new TypeScript file in src/systems/
2. Export a class with clear interfaces
3. Add comprehensive documentation
4. Include proper error handling
5. Add to the main WorldComponent integration

Adding New Objects

1. Create a new TypeScript file in src/components/objects/
2. Extend or use Three.js objects appropriately
3. Implement a tick() method if animation is needed
4. Add proper cleanup methods
5. Document the object's purpose and usage

Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

• Write unit tests for all public methods
• Test error conditions and edge cases
• Use descriptive test names
• Mock external dependencies
• Test Three.js objects in isolation

Pull Request Process

Before Submitting

1. Ensure code quality

   • Run npm run type-check
   • Run npm run lint
   • Run npm run format
   • All tests pass

2. Update documentation

   • Update README.md if needed
   • Add JSDoc comments for new methods
   • Update any relevant documentation

3. Test thoroughly

   • Test in different browsers
   • Test with different screen sizes
   • Test performance impact

Pull Request Guidelines

1. Create a descriptive title

   • Use conventional commit format
   • Be specific about the change

2. Write a detailed description

   • Explain what the PR does
   • Include screenshots for UI changes
   • Reference related issues

3. Keep PRs focused

   • One feature or fix per PR
   • Keep changes manageable
   • Break large changes into smaller PRs

Code Review Guidelines

Review Process

1. Automated checks must pass

   • TypeScript compilation
   • Linting
   • Tests

2. Manual review checklist

   • Code follows project standards
   • Documentation is complete
   • Error handling is appropriate
   • Performance impact is considered
   • Security implications are addressed

Review Comments

• Be constructive and specific
• Suggest improvements when possible
• Ask questions for clarification
• Use inline comments for specific issues

Security Considerations

Code Review Checklist

• No hardcoded secrets or API keys
• Input validation is implemented
• Error messages don't expose sensitive information
• External dependencies are from trusted sources
• Three.js objects are properly disposed
• No XSS vulnerabilities in dynamic content

Reporting Security Issues

If you discover a security vulnerability, please:

1. Do not create a public issue
2. Email the maintainer directly
3. Provide detailed information
4. Allow time for response

Getting Help

• Documentation: Check the README.md and inline documentation
• Issues: Search existing issues before creating new ones
• Discussions: Use GitHub Discussions for questions
• Chat: Join our community chat (if available)

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for contributing to World Component! Your efforts help make this project better for everyone.