|
| 1 | +# Contributing to XE IWA Launcher |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the XE IWA Launcher project! This document provides guidelines for contributing to the project and its plugin ecosystem. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Code of Conduct](#code-of-conduct) |
| 8 | +- [Getting Started](#getting-started) |
| 9 | +- [Development Setup](#development-setup) |
| 10 | +- [Project Structure](#project-structure) |
| 11 | +- [Plugin Development](#plugin-development) |
| 12 | +- [Contribution Process](#contribution-process) |
| 13 | +- [Coding Standards](#coding-standards) |
| 14 | +- [Testing Guidelines](#testing-guidelines) |
| 15 | +- [Documentation](#documentation) |
| 16 | +- [Release Process](#release-process) |
| 17 | + |
| 18 | +## Code of Conduct |
| 19 | + |
| 20 | +We are committed to providing a welcoming and inclusive environment for all contributors. Please: |
| 21 | + |
| 22 | +- Be respectful and considerate in all interactions |
| 23 | +- Welcome newcomers and help them get started |
| 24 | +- Focus on constructive criticism and collaborative problem-solving |
| 25 | +- Respect differing viewpoints and experiences |
| 26 | + |
| 27 | +## Getting Started |
| 28 | + |
| 29 | +1. **Fork the repository** on GitHub |
| 30 | +2. **Clone your fork** locally: |
| 31 | + ```bash |
| 32 | + git clone https://github.com/your-username/xe-iwa-launcher.git |
| 33 | + cd xe-iwa-launcher |
| 34 | + ``` |
| 35 | +3. **Add upstream remote**: |
| 36 | + ```bash |
| 37 | + git remote add upstream https://github.com/original-owner/xe-iwa-launcher.git |
| 38 | + ``` |
| 39 | +4. **Install dependencies**: |
| 40 | + ```bash |
| 41 | + bun install |
| 42 | + cd src-tauri && cargo build |
| 43 | + ``` |
| 44 | + |
| 45 | +## Development Setup |
| 46 | + |
| 47 | +### Prerequisites |
| 48 | + |
| 49 | +- **Bun** (latest version) - JavaScript runtime and package manager |
| 50 | +- **Rust** (latest stable) - For Tauri backend |
| 51 | +- **Node.js** (v18+) - Some tools may require Node.js |
| 52 | +- **Tauri CLI** - Install via `cargo install tauri-cli` |
| 53 | + |
| 54 | +### Platform-Specific Requirements |
| 55 | + |
| 56 | +#### macOS |
| 57 | +- Xcode Command Line Tools |
| 58 | +- For Podman plugin: Rosetta 2 (`softwareupdate --install-rosetta`) |
| 59 | +- For keyboard plugins: Grant accessibility permissions |
| 60 | + |
| 61 | +#### Windows |
| 62 | +- Microsoft Visual Studio C++ Build Tools |
| 63 | +- WebView2 (usually pre-installed on Windows 10/11) |
| 64 | +- For Podman plugin: WSL2 |
| 65 | + |
| 66 | +#### Linux |
| 67 | +- Development libraries: `libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev` |
| 68 | +- For keyboard plugins: X11 development headers |
| 69 | + |
| 70 | +### Running the Development Environment |
| 71 | + |
| 72 | +```bash |
| 73 | +# Start the development server |
| 74 | +bun run dev |
| 75 | + |
| 76 | +# Run the app with Tauri |
| 77 | +bun run tauri dev |
| 78 | + |
| 79 | +# Build for production |
| 80 | +bun run tauri build |
| 81 | +``` |
| 82 | + |
| 83 | +## Project Structure |
| 84 | + |
| 85 | +``` |
| 86 | +xe-iwa-launcher/ |
| 87 | +├── src/ # Frontend React/TypeScript code |
| 88 | +│ ├── components/ # React components |
| 89 | +│ ├── types/ # TypeScript type definitions |
| 90 | +│ └── App.tsx # Main application component |
| 91 | +├── src-tauri/ # Backend Rust code |
| 92 | +│ ├── src/ # Main Tauri application |
| 93 | +│ ├── capabilities/ # Permission configurations |
| 94 | +│ └── binaries/ # Platform-specific binaries |
| 95 | +├── tauri-plugin-*/ # Individual plugin directories |
| 96 | +│ ├── src/ # Plugin Rust implementation |
| 97 | +│ ├── guest-js/ # Plugin TypeScript bindings |
| 98 | +│ └── README.md # Plugin documentation |
| 99 | +└── docs/ # Project documentation |
| 100 | +``` |
| 101 | + |
| 102 | +## Plugin Development |
| 103 | + |
| 104 | +### Creating a New Plugin |
| 105 | + |
| 106 | +1. **Generate plugin structure**: |
| 107 | + ```bash |
| 108 | + cargo tauri plugin new my-plugin |
| 109 | + cd tauri-plugin-my-plugin |
| 110 | + ``` |
| 111 | + |
| 112 | +2. **Define your plugin API** in `src/models.rs`: |
| 113 | + ```rust |
| 114 | + use serde::{Deserialize, Serialize}; |
| 115 | + |
| 116 | + #[derive(Debug, Serialize, Deserialize)] |
| 117 | + #[serde(rename_all = "camelCase")] |
| 118 | + pub struct MyRequest { |
| 119 | + pub value: String, |
| 120 | + } |
| 121 | + ``` |
| 122 | + |
| 123 | +3. **Implement commands** in `src/commands.rs`: |
| 124 | + ```rust |
| 125 | + use tauri::command; |
| 126 | + |
| 127 | + #[command] |
| 128 | + pub async fn my_command(request: MyRequest) -> Result<String> { |
| 129 | + Ok(format!("Processed: {}", request.value)) |
| 130 | + } |
| 131 | + ``` |
| 132 | + |
| 133 | +4. **Register the plugin** in `src/lib.rs`: |
| 134 | + ```rust |
| 135 | + use tauri::plugin::{Builder, TauriPlugin}; |
| 136 | + |
| 137 | + pub fn init<R: Runtime>() -> TauriPlugin<R> { |
| 138 | + Builder::new("my-plugin") |
| 139 | + .invoke_handler(tauri::generate_handler![ |
| 140 | + commands::my_command, |
| 141 | + ]) |
| 142 | + .build() |
| 143 | + } |
| 144 | + ``` |
| 145 | + |
| 146 | +5. **Create TypeScript bindings** in `guest-js/index.ts`: |
| 147 | + ```typescript |
| 148 | + import { invoke } from '@tauri-apps/api/core'; |
| 149 | + |
| 150 | + export async function myCommand(value: string): Promise<string> { |
| 151 | + return await invoke('plugin:my-plugin|my_command', { value }); |
| 152 | + } |
| 153 | + ``` |
| 154 | + |
| 155 | +6. **Add comprehensive documentation** in `README.md` |
| 156 | + |
| 157 | +### Plugin Best Practices |
| 158 | + |
| 159 | +- **State Management**: Use Tauri's state management for shared data |
| 160 | +- **Error Handling**: Implement proper error types with `thiserror` |
| 161 | +- **Async Operations**: Use `async/await` for non-blocking operations |
| 162 | +- **Platform Compatibility**: Use conditional compilation for platform-specific code |
| 163 | +- **Security**: Validate all inputs and use Tauri's permission system |
| 164 | +- **Performance**: Profile and optimize resource-intensive operations |
| 165 | + |
| 166 | +## Contribution Process |
| 167 | + |
| 168 | +### Reporting Issues |
| 169 | + |
| 170 | +1. **Check existing issues** to avoid duplicates |
| 171 | +2. **Use issue templates** when available |
| 172 | +3. **Provide detailed information**: |
| 173 | + - Steps to reproduce |
| 174 | + - Expected vs actual behavior |
| 175 | + - System information |
| 176 | + - Error messages/logs |
| 177 | + |
| 178 | +### Submitting Pull Requests |
| 179 | + |
| 180 | +1. **Create a feature branch**: |
| 181 | + ```bash |
| 182 | + git checkout -b feature/my-feature |
| 183 | + ``` |
| 184 | + |
| 185 | +2. **Make your changes**: |
| 186 | + - Follow coding standards |
| 187 | + - Add tests for new functionality |
| 188 | + - Update documentation |
| 189 | + |
| 190 | +3. **Commit with descriptive messages**: |
| 191 | + ```bash |
| 192 | + git commit -m "feat: add new feature for X |
| 193 | + |
| 194 | + - Detail 1 |
| 195 | + - Detail 2 |
| 196 | + |
| 197 | + Closes #123" |
| 198 | + ``` |
| 199 | + |
| 200 | +4. **Push and create PR**: |
| 201 | + ```bash |
| 202 | + git push origin feature/my-feature |
| 203 | + ``` |
| 204 | + |
| 205 | +5. **PR Guidelines**: |
| 206 | + - Reference related issues |
| 207 | + - Describe changes clearly |
| 208 | + - Include screenshots for UI changes |
| 209 | + - Ensure all tests pass |
| 210 | + - Request review from maintainers |
| 211 | + |
| 212 | +### Commit Message Format |
| 213 | + |
| 214 | +We follow Conventional Commits: |
| 215 | + |
| 216 | +- `feat:` New features |
| 217 | +- `fix:` Bug fixes |
| 218 | +- `docs:` Documentation changes |
| 219 | +- `style:` Code style changes (formatting, etc.) |
| 220 | +- `refactor:` Code refactoring |
| 221 | +- `test:` Test additions/changes |
| 222 | +- `chore:` Build process or auxiliary tool changes |
| 223 | + |
| 224 | +## Coding Standards |
| 225 | + |
| 226 | +### Rust Code |
| 227 | + |
| 228 | +- Use `rustfmt` for formatting |
| 229 | +- Run `clippy` and address warnings |
| 230 | +- Follow Rust naming conventions |
| 231 | +- Document public APIs with doc comments |
| 232 | +- Use `Result<T, Error>` for error handling |
| 233 | + |
| 234 | +### TypeScript/JavaScript |
| 235 | + |
| 236 | +- Use ESLint and Prettier configurations |
| 237 | +- Prefer TypeScript over JavaScript |
| 238 | +- Use functional components with hooks in React |
| 239 | +- Implement proper error boundaries |
| 240 | +- Follow React best practices |
| 241 | + |
| 242 | +### General Guidelines |
| 243 | + |
| 244 | +- **DRY** (Don't Repeat Yourself) |
| 245 | +- **KISS** (Keep It Simple, Stupid) |
| 246 | +- **YAGNI** (You Aren't Gonna Need It) |
| 247 | +- Write self-documenting code |
| 248 | +- Add comments for complex logic |
| 249 | + |
| 250 | +## Testing Guidelines |
| 251 | + |
| 252 | +### Unit Tests |
| 253 | + |
| 254 | +```rust |
| 255 | +#[cfg(test)] |
| 256 | +mod tests { |
| 257 | + use super::*; |
| 258 | + |
| 259 | + #[test] |
| 260 | + fn test_my_function() { |
| 261 | + assert_eq!(my_function("input"), "expected"); |
| 262 | + } |
| 263 | +} |
| 264 | +``` |
| 265 | + |
| 266 | +### Integration Tests |
| 267 | + |
| 268 | +- Test plugin integration with main app |
| 269 | +- Test cross-platform compatibility |
| 270 | +- Test error scenarios |
| 271 | + |
| 272 | +### Manual Testing |
| 273 | + |
| 274 | +- Test on all supported platforms |
| 275 | +- Test with different system configurations |
| 276 | +- Test accessibility features |
| 277 | +- Performance testing with profiling tools |
| 278 | + |
| 279 | +## Documentation |
| 280 | + |
| 281 | +### Code Documentation |
| 282 | + |
| 283 | +- Document all public APIs |
| 284 | +- Include usage examples |
| 285 | +- Explain complex algorithms |
| 286 | +- Document platform-specific behavior |
| 287 | + |
| 288 | +### README Files |
| 289 | + |
| 290 | +Each plugin must have a README with: |
| 291 | +- Feature list |
| 292 | +- Installation instructions |
| 293 | +- API reference |
| 294 | +- Usage examples |
| 295 | +- Platform support matrix |
| 296 | +- Troubleshooting section |
| 297 | + |
| 298 | +### API Documentation |
| 299 | + |
| 300 | +- Use JSDoc/TSDoc for TypeScript |
| 301 | +- Use rustdoc for Rust |
| 302 | +- Keep documentation up-to-date |
| 303 | +- Include code examples |
| 304 | + |
| 305 | +## Release Process |
| 306 | + |
| 307 | +### Version Bumping |
| 308 | + |
| 309 | +1. Update version in: |
| 310 | + - `package.json` |
| 311 | + - `src-tauri/Cargo.toml` |
| 312 | + - Plugin `Cargo.toml` files |
| 313 | + |
| 314 | +2. Update `CHANGELOG.md` |
| 315 | + |
| 316 | +3. Create release commit: |
| 317 | + ```bash |
| 318 | + git commit -m "chore: release v1.2.3" |
| 319 | + ``` |
| 320 | + |
| 321 | +### Creating Releases |
| 322 | + |
| 323 | +1. Tag the release: |
| 324 | + ```bash |
| 325 | + git tag v1.2.3 |
| 326 | + git push origin v1.2.3 |
| 327 | + ``` |
| 328 | + |
| 329 | +2. GitHub Actions will: |
| 330 | + - Build for all platforms |
| 331 | + - Run tests |
| 332 | + - Create draft release |
| 333 | + - Upload artifacts |
| 334 | + |
| 335 | +3. Manually: |
| 336 | + - Review release notes |
| 337 | + - Test artifacts |
| 338 | + - Publish release |
| 339 | + |
| 340 | +## Plugin Architecture Guidelines |
| 341 | + |
| 342 | +### Plugin Independence |
| 343 | + |
| 344 | +- Plugins should be self-contained |
| 345 | +- Minimize dependencies between plugins |
| 346 | +- Use events for inter-plugin communication |
| 347 | +- Document all plugin interactions |
| 348 | + |
| 349 | +### Configuration Management |
| 350 | + |
| 351 | +- Support both compile-time and runtime configuration |
| 352 | +- Use feature flags for optional functionality |
| 353 | +- Provide sensible defaults |
| 354 | +- Validate configuration values |
| 355 | + |
| 356 | +### Resource Management |
| 357 | + |
| 358 | +- Clean up resources properly |
| 359 | +- Handle plugin lifecycle events |
| 360 | +- Implement graceful shutdown |
| 361 | +- Monitor memory usage |
| 362 | + |
| 363 | +## Questions and Support |
| 364 | + |
| 365 | +- **Discord**: Join our community server |
| 366 | +- **GitHub Discussions**: For general questions |
| 367 | +- **Issues**: For bug reports and feature requests |
| 368 | +- **Email**: maintainers@example.com |
| 369 | + |
| 370 | +## Recognition |
| 371 | + |
| 372 | +Contributors will be recognized in: |
| 373 | +- `CONTRIBUTORS.md` file |
| 374 | +- Release notes |
| 375 | +- Project documentation |
| 376 | + |
| 377 | +Thank you for contributing to XE IWA Launcher! |
0 commit comments