Create initial documentation structure

docs/development/contributing.md

@@ -0,0 +1,373 @@
+# Contributing
+
+Thank you for your interest in contributing to LlamaCtl! This guide will help you get started with development and contribution.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.24 or later
+- Node.js 22 or later
+- `llama-server` executable (from [llama.cpp](https://github.com/ggml-org/llama.cpp))
+- Git
+
+### Getting Started
+
+1. **Fork and Clone**
+   ```bash
+   # Fork the repository on GitHub, then clone your fork
+   git clone https://github.com/yourusername/llamactl.git
+   cd llamactl
+   
+   # Add upstream remote
+   git remote add upstream https://github.com/lordmathis/llamactl.git
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   # Go dependencies
+   go mod download
+   
+   # Frontend dependencies
+   cd webui && npm ci && cd ..
+   ```
+
+3. **Run Development Environment**
+   ```bash
+   # Start backend server
+   go run ./cmd/server
+   ```
+   
+   In a separate terminal:
+   ```bash
+   # Start frontend dev server
+   cd webui && npm run dev
+   ```
+
+## Development Workflow
+
+### Setting Up Your Environment
+
+1. **Configuration**
+   Create a development configuration file:
+   ```yaml
+   # dev-config.yaml
+   server:
+     host: "localhost"
+     port: 8080
+   logging:
+     level: "debug"
+   ```
+
+2. **Test Data**
+   Set up test models and instances for development.
+
+### Making Changes
+
+1. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Development Commands**
+   ```bash
+   # Backend
+   go test ./... -v                    # Run tests
+   go test -race ./... -v              # Run with race detector
+   go fmt ./... && go vet ./...        # Format and vet code
+   go build ./cmd/server               # Build binary
+   
+   # Frontend (from webui/ directory)
+   npm run test                        # Run tests
+   npm run lint                        # Lint code
+   npm run type-check                  # TypeScript check
+   npm run build                       # Build for production
+   ```
+
+3. **Code Quality**
+   ```bash
+   # Run all checks before committing
+   make lint
+   make test
+   make build
+   ```
+
+## Project Structure
+
+### Backend (Go)
+
+```
+cmd/
+├── server/              # Main application entry point
+pkg/
+├── backends/           # Model backend implementations
+├── config/            # Configuration management
+├── instance/          # Instance lifecycle management
+├── manager/           # Instance manager
+├── server/            # HTTP server and routes
+├── testutil/          # Test utilities
+└── validation/        # Input validation
+```
+
+### Frontend (React/TypeScript)
+
+```
+webui/src/
+├── components/        # React components
+├── contexts/         # React contexts
+├── hooks/           # Custom hooks
+├── lib/             # Utility libraries
+├── schemas/         # Zod schemas
+└── types/           # TypeScript types
+```
+
+## Coding Standards
+
+### Go Code
+
+- Follow standard Go formatting (`gofmt`)
+- Use `go vet` and address all warnings
+- Write comprehensive tests for new functionality
+- Include documentation comments for exported functions
+- Use meaningful variable and function names
+
+Example:
+```go
+// CreateInstance creates a new model instance with the given configuration.
+// It validates the configuration and ensures the instance name is unique.
+func (m *Manager) CreateInstance(ctx context.Context, config InstanceConfig) (*Instance, error) {
+    if err := config.Validate(); err != nil {
+        return nil, fmt.Errorf("invalid configuration: %w", err)
+    }
+    
+    // Implementation...
+}
+```
+
+### TypeScript/React Code
+
+- Use TypeScript strict mode
+- Follow React best practices
+- Use functional components with hooks
+- Implement proper error boundaries
+- Write unit tests for components
+
+Example:
+```typescript
+interface InstanceCardProps {
+  instance: Instance;
+  onStart: (name: string) => Promise<void>;
+  onStop: (name: string) => Promise<void>;
+}
+
+export const InstanceCard: React.FC<InstanceCardProps> = ({
+  instance,
+  onStart,
+  onStop,
+}) => {
+  // Implementation...
+};
+```
+
+## Testing
+
+### Backend Tests
+
+```bash
+# Run all tests
+go test ./...
+
+# Run tests with coverage
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out
+
+# Run specific package tests
+go test ./pkg/manager -v
+
+# Run with race detection
+go test -race ./...
+```
+
+### Frontend Tests
+
+```bash
+cd webui
+
+# Run unit tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run E2E tests
+npm run test:e2e
+```
+
+### Integration Tests
+
+```bash
+# Run integration tests (requires llama-server)
+go test ./... -tags=integration
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Update your branch**
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Run all tests**
+   ```bash
+   make test-all
+   ```
+
+3. **Update documentation** if needed
+
+4. **Write clear commit messages**
+   ```
+   feat: add instance health monitoring
+   
+   - Implement health check endpoint
+   - Add periodic health monitoring
+   - Update API documentation
+   
+   Fixes #123
+   ```
+
+### Submitting a PR
+
+1. **Push your branch**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+2. **Create Pull Request**
+   - Use the PR template
+   - Provide clear description
+   - Link related issues
+   - Add screenshots for UI changes
+
+3. **PR Review Process**
+   - Automated checks must pass
+   - Code review by maintainers
+   - Address feedback promptly
+   - Keep PR scope focused
+
+## Issue Guidelines
+
+### Reporting Bugs
+
+Use the bug report template and include:
+
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, Go version, etc.)
+- Relevant logs or error messages
+- Minimal reproduction case
+
+### Feature Requests
+
+Use the feature request template and include:
+
+- Clear description of the problem
+- Proposed solution
+- Alternative solutions considered
+- Implementation complexity estimate
+
+### Security Issues
+
+For security vulnerabilities:
+- Do NOT create public issues
+- Email security@llamactl.dev
+- Provide detailed description
+- Allow time for fix before disclosure
+
+## Development Best Practices
+
+### API Design
+
+- Follow REST principles
+- Use consistent naming conventions
+- Provide comprehensive error messages
+- Include proper HTTP status codes
+- Document all endpoints
+
+### Error Handling
+
+```go
+// Wrap errors with context
+if err := instance.Start(); err != nil {
+    return fmt.Errorf("failed to start instance %s: %w", instance.Name, err)
+}
+
+// Use structured logging
+log.WithFields(log.Fields{
+    "instance": instance.Name,
+    "error": err,
+}).Error("Failed to start instance")
+```
+
+### Configuration
+
+- Use environment variables for deployment
+- Provide sensible defaults
+- Validate configuration on startup
+- Support configuration file reloading
+
+### Performance
+
+- Profile code for bottlenecks
+- Use efficient data structures
+- Implement proper caching
+- Monitor resource usage
+
+## Release Process
+
+### Version Management
+
+- Use semantic versioning (SemVer)
+- Tag releases properly
+- Maintain CHANGELOG.md
+- Create release notes
+
+### Building Releases
+
+```bash
+# Build all platforms
+make build-all
+
+# Create release package
+make package
+```
+
+## Getting Help
+
+### Communication Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: General questions and ideas
+- **Code Review**: PR comments and feedback
+
+### Development Questions
+
+When asking for help:
+
+1. Check existing documentation
+2. Search previous issues
+3. Provide minimal reproduction case
+4. Include relevant environment details
+
+## Recognition
+
+Contributors are recognized in:
+
+- CONTRIBUTORS.md file
+- Release notes
+- Documentation credits
+- Annual contributor highlights
+
+Thank you for contributing to LlamaCtl!