Contributing to XE Launcher

Thank you for your interest in contributing to the XE Launcher project! This document provides guidelines for contributing to the project and its plugin ecosystem.

Code of Conduct
Getting Started
Development Setup
Project Structure
Plugin Development
Contribution Process
Coding Standards
Testing Guidelines
Documentation
Release Process

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

Be respectful and considerate in all interactions
Welcome newcomers and help them get started
Focus on constructive criticism and collaborative problem-solving
Respect differing viewpoints and experiences

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/xe-launcher.git
cd xe-launcher

Add upstream remote:

git remote add upstream https://github.com/Agent54/xe-launcher.git

Install dependencies:
```
bun install
cd src-tauri && cargo build
```

Development Setup

Prerequisites

Bun (latest version) - JavaScript runtime and package manager
Rust (latest stable) - For Tauri backend
Node.js (v18+) - Some tools may require Node.js
Tauri CLI - Install via cargo install tauri-cli

Platform-Specific Requirements

macOS

Xcode Command Line Tools
For Podman plugin: Rosetta 2 (softwareupdate --install-rosetta)
For keyboard plugins: Grant accessibility permissions

Windows

Microsoft Visual Studio C++ Build Tools
WebView2 (usually pre-installed on Windows 10/11)
For Podman plugin: WSL2

Linux

Development libraries: libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
For keyboard plugins: X11 development headers

Running the Development Environment

# Start the development server
bun run dev

# Run the app with Tauri
bun run tauri dev

# Build for production
bun run tauri build

Project Structure

xe-iwa-launcher/
├── src/                    # Frontend React/TypeScript code
│   ├── components/         # React components
│   ├── types/              # TypeScript type definitions
│   └── App.tsx            # Main application component
├── src-tauri/             # Backend Rust code
│   ├── src/               # Main Tauri application
│   ├── capabilities/      # Permission configurations
│   └── binaries/          # Platform-specific binaries
├── tauri-plugin-*/        # Individual plugin directories
│   ├── src/               # Plugin Rust implementation
│   ├── guest-js/          # Plugin TypeScript bindings
│   └── README.md          # Plugin documentation
└── docs/                  # Project documentation

Plugin Development

Creating a New Plugin

Generate plugin structure:

cargo tauri plugin new my-plugin
cd tauri-plugin-my-plugin

Define your plugin API in src/models.rs:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MyRequest {
    pub value: String,
}

Implement commands in src/commands.rs:

use tauri::command;

#[command]
pub async fn my_command(request: MyRequest) -> Result<String> {
    Ok(format!("Processed: {}", request.value))
}

Register the plugin in src/lib.rs:

use tauri::plugin::{Builder, TauriPlugin};

pub fn init<R: Runtime>() -> TauriPlugin<R> {
    Builder::new("my-plugin")
        .invoke_handler(tauri::generate_handler![
            commands::my_command,
        ])
        .build()
}

Create TypeScript bindings in guest-js/index.ts:

import { invoke } from '@tauri-apps/api/core';

export async function myCommand(value: string): Promise<string> {
    return await invoke('plugin:my-plugin|my_command', { value });
}

Add comprehensive documentation in README.md

Plugin Best Practices

State Management: Use Tauri's state management for shared data
Error Handling: Implement proper error types with thiserror
Async Operations: Use async/await for non-blocking operations
Platform Compatibility: Use conditional compilation for platform-specific code
Security: Validate all inputs and use Tauri's permission system
Performance: Profile and optimize resource-intensive operations

Contribution Process

Reporting Issues

Check existing issues to avoid duplicates
Use issue templates when available
Provide detailed information:
- Steps to reproduce
- Expected vs actual behavior
- System information
- Error messages/logs

Submitting Pull Requests

Create a feature branch:
```
git checkout -b feature/my-feature
```
Make your changes:
- Follow coding standards
- Add tests for new functionality
- Update documentation

Commit with descriptive messages:

git commit -m "feat: add new feature for X

- Detail 1
- Detail 2

Closes #123"

Push and create PR:
```
git push origin feature/my-feature
```
PR Guidelines:
- Reference related issues
- Describe changes clearly
- Include screenshots for UI changes
- Ensure all tests pass
- Request review from maintainers

Commit Message Format

We follow Conventional Commits:

feat: New features
fix: Bug fixes
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Test additions/changes
chore: Build process or auxiliary tool changes

Coding Standards

Rust Code

Use rustfmt for formatting
Run clippy and address warnings
Follow Rust naming conventions
Document public APIs with doc comments
Use Result<T, Error> for error handling

TypeScript/JavaScript

Use ESLint and Prettier configurations
Prefer TypeScript over JavaScript
Use functional components with hooks in React
Implement proper error boundaries
Follow React best practices

General Guidelines

DRY (Don't Repeat Yourself)
KISS (Keep It Simple, Stupid)
YAGNI (You Aren't Gonna Need It)
Write self-documenting code
Add comments for complex logic

Testing Guidelines

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_my_function() {
        assert_eq!(my_function("input"), "expected");
    }
}

Integration Tests

Test plugin integration with main app
Test cross-platform compatibility
Test error scenarios

Manual Testing

Test on all supported platforms
Test with different system configurations
Test accessibility features
Performance testing with profiling tools

Documentation

Code Documentation

Document all public APIs
Include usage examples
Explain complex algorithms
Document platform-specific behavior

README Files

Each plugin must have a README with:

Feature list
Installation instructions
API reference
Usage examples
Platform support matrix
Troubleshooting section

API Documentation

Use JSDoc/TSDoc for TypeScript
Use rustdoc for Rust
Keep documentation up-to-date
Include code examples

Release Process

Version Bumping

Update version in:
- package.json
- src-tauri/Cargo.toml
- Plugin Cargo.toml files
Update CHANGELOG.md
Create release commit:
```
git commit -m "chore: release v1.2.3"
```

Creating Releases

Tag the release:
```
git tag v1.2.3
git push origin v1.2.3
```
GitHub Actions will:
- Build for all platforms
- Run tests
- Create draft release
- Upload artifacts
Manually:
- Review release notes
- Test artifacts
- Publish release

Plugin Architecture Guidelines

Plugin Independence

Plugins should be self-contained
Minimize dependencies between plugins
Use events for inter-plugin communication
Document all plugin interactions

Configuration Management

Support both compile-time and runtime configuration
Use feature flags for optional functionality
Provide sensible defaults
Validate configuration values

Resource Management

Clean up resources properly
Handle plugin lifecycle events
Implement graceful shutdown
Monitor memory usage

Questions and Support

Discord: Join our community server
GitHub Discussions: For general questions
Issues: For bug reports and feature requests
Email: maintainers@example.com

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Thank you for contributing to XE IWA Launcher!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History