Skip to content
This repository was archived by the owner on Aug 7, 2025. It is now read-only.

Commit bc0da4c

Browse files
lukeclaude
andcommitted
docs: Comprehensive documentation update for all plugins
- Created detailed README.md for each plugin: - tauri-plugin-chrome-manager: Chrome instance management - tauri-plugin-podman: Container orchestration - tauri-plugin-workerd: Cloudflare Workers runtime - tauri-plugin-capslock-remap: Caps Lock key remapping - tauri-plugin-ollama: Local AI model integration - tauri-plugin-keyboard: Global hotkeys (in development) - Added CONTRIBUTING.md with: - Development setup instructions - Plugin development guidelines - Coding standards and best practices - Contribution process - Created docs/API_REFERENCE.md with: - Complete API documentation for all plugins - TypeScript interfaces and examples - Event system documentation - Error handling patterns - Updated main README.md with: - Plugin overview table - Status indicators - Platform support matrix - Links to detailed documentation This documentation provides a solid foundation for parallel development and makes the project more maintainable and accessible to contributors. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 789ac9a commit bc0da4c

File tree

9 files changed

+2698
-2
lines changed

9 files changed

+2698
-2
lines changed

CONTRIBUTING.md

Lines changed: 377 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,377 @@
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

Comments
 (0)