Skip to content

Commit 19f9467

Browse files
Copilotdoublegate
Copilot
and
doublegate
authored
Add GitHub Copilot instructions for repository (#30)
* Initial plan * Add GitHub Copilot instructions file Co-authored-by: doublegate <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: doublegate <[email protected]>
1 parent a30f166 commit 19f9467

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# GitHub Copilot Instructions for RustIRC
2+
3+
## Project Overview
4+
5+
RustIRC is a modern IRC client built in Rust that combines the best features from established IRC clients (mIRC, HexChat, WeeChat). The project prioritizes full IRC protocol compliance (RFC 1459/2812, IRCv3), cross-platform support (Windows, macOS, Linux), and provides multiple interface modes (GUI with Iced 0.13.1, TUI with ratatui, CLI).
6+
7+
**Current Version**: v0.3.8 - Enhanced Iced Material Design GUI
8+
**Status**: Production-ready with 100% functional Material Design 3 implementation
9+
10+
## Technology Stack
11+
12+
- **Language**: Rust (MSRV: 1.75+)
13+
- **Async Runtime**: Tokio for network I/O
14+
- **GUI Framework**: Iced 0.13.1 with Material Design 3 components
15+
- **TUI Framework**: ratatui for terminal interface
16+
- **Security**: rustls for TLS, complete SASL authentication (PLAIN, EXTERNAL, SCRAM-SHA-256)
17+
- **Scripting**: mlua for Lua integration
18+
- **Architecture**: Event-driven with modular 6-crate workspace structure
19+
20+
## Essential Commands
21+
22+
### Building and Running
23+
```bash
24+
# Build the project
25+
cargo build
26+
cargo build --release
27+
28+
# Run in different modes
29+
cargo run # GUI mode (default)
30+
cargo run -- --cli # CLI prototype mode
31+
cargo run -- --tui # TUI mode with ratatui
32+
cargo run -- --config path/to/config.toml # Custom config
33+
34+
# Run tests
35+
cargo test
36+
cargo test -- --nocapture # Show println! output
37+
```
38+
39+
### Code Quality
40+
```bash
41+
# Format code (required before commits)
42+
cargo fmt
43+
44+
# Lint code (must pass before commits)
45+
cargo clippy -- -D warnings
46+
47+
# Pre-commit check
48+
cargo fmt --check && cargo clippy -- -D warnings
49+
50+
# Generate documentation
51+
cargo doc --open
52+
```
53+
54+
## Coding Standards
55+
56+
### Critical Rules
57+
1. **Zero Placeholder Code**: Never leave "TODO" or "In a real implementation" comments. Implement all functionality completely.
58+
2. **No Removal Strategy**: Fix compilation errors by implementing missing functionality, never by removing/disabling features.
59+
3. **Complete Platform Support**: Implement full Windows (PowerShell), macOS (osascript), Linux (notify-send) support using conditional compilation.
60+
4. **Error Handling**: Always use proper Result types with descriptive error messages. Follow Rust error handling idioms.
61+
5. **Memory Safety**: Leverage Rust's ownership model. Use references appropriately, avoid unnecessary clones unless required for lifetime management.
62+
63+
### Rust Best Practices
64+
- Follow Rust naming conventions (snake_case for functions/variables, CamelCase for types)
65+
- Use `async/await` with Tokio for all network operations
66+
- Implement proper trait bounds and lifetime annotations
67+
- Disable pagers in git commands: `git --no-pager`
68+
- Use `#[cfg(target_os = "...")]` for platform-specific code
69+
70+
### IRC Protocol Specifics
71+
- **Field Naming**: Verify against protocol definitions (e.g., WHOIS uses `targets` not `target`)
72+
- **Message Filtering**: Handle case-sensitive filtering (both "System" and "system")
73+
- **Command Implementation**: Use `rustirc_protocol::Command` for IRC method implementation
74+
- **Protocol Compliance**: Full support for RFC 1459/2812 and IRCv3 extensions
75+
76+
### GUI Development (Iced 0.13.1)
77+
- Use proper border syntax with `0.0.into()` for radius
78+
- Apply container styling for pane dividers
79+
- Implement Material Design 3 patterns with SerializableColor wrapper
80+
- Use `.into()` conversions for automatic color type conversions
81+
- Handle lifetime issues with clone-before-move pattern
82+
83+
## Common Patterns
84+
85+
### Compilation Error Resolution
86+
1. **Type Mismatches**: Convert types properly using Into/From traits
87+
2. **Lifetime Issues**: Use clone-before-move pattern: `let value = data.clone(); move || { use value }`
88+
3. **Borrow Checker**: Extract values before closures to satisfy borrow checker
89+
4. **Platform Code**: Use conditional compilation with complete implementations
90+
91+
### Multi-Server Architecture
92+
- Use `HashMap<String, ServerData>` for server management
93+
- Check server-specific connection state before IRC operations
94+
- Implement proper command routing with server validation
95+
- Provide informative error messages for unavailable servers
96+
97+
### Material Design 3 Integration
98+
- SerializableColor wrapper for config persistence: `[f32; 4]` with serde traits
99+
- Implement `.scale_alpha()` for transparency adjustments
100+
- Use `.build()` APIs for MaterialText/MaterialButton components
101+
- Apply responsive layouts with proper enum traits
102+
103+
## Testing Strategy
104+
- Unit tests for protocol commands
105+
- Integration tests for connection scenarios
106+
- Mock IRC servers for edge cases
107+
- UI tests using framework-specific tools
108+
- Performance benchmarks for message throughput
109+
- Security audits for input validation
110+
111+
## GitHub Actions / CI/CD
112+
- BASH_ENV helper functions required for cross-platform timeout support
113+
- sccache HTTP 400 fallback to local disk cache
114+
- Timeout protection for all cargo operations
115+
- Clippy must run AFTER successful build completion
116+
- All platforms must pass: Windows, Linux (x64/ARM64), macOS (x64/ARM64)
117+
118+
## Directory Structure
119+
```
120+
RustIRC/
121+
├── src/ # Application entry point and main logic
122+
├── crates/ # Modular crate structure (6 crates)
123+
├── tests/ # Integration tests
124+
├── docs/ # User documentation
125+
├── ref_docs/ # Reference materials and development plans
126+
├── to-dos/ # Phase-specific task lists
127+
├── .github/ # GitHub workflows and configurations
128+
└── scripts/ # Development and build scripts
129+
```
130+
131+
## Security Considerations
132+
- All network communication over TLS by default
133+
- Secure credential storage (system keychain integration)
134+
- Sandboxed scripting environment
135+
- Input validation against malformed IRC messages
136+
- DCC security warnings and IP masking options
137+
138+
## Documentation Requirements
139+
- Maintain rustdoc comments for all public APIs
140+
- Include examples in documentation
141+
- Update CHANGELOG.md for all user-facing changes
142+
- Keep README.md badges and status up to date
143+
- Document all architectural decisions
144+
145+
## Performance Goals
146+
- Handle 100+ simultaneous channels without lag
147+
- Efficient user list management with optimized data structures
148+
- Background logging and message processing
149+
- Responsive UI even under heavy message load
150+
- 60 FPS animations in GUI mode
151+
152+
## Common Pitfalls to Avoid
153+
❌ Running clippy before or parallel to build
154+
❌ Using restore-keys parameter with Swatinem/rust-cache@v2
155+
❌ Leaving placeholder/stub code
156+
❌ Removing features to fix compilation errors
157+
❌ Using matrix.os in shell expressions with workflow_call
158+
❌ Missing platform-specific implementations
159+
160+
✅ Implement complete functionality immediately
161+
✅ Run clippy after successful build
162+
✅ Use proper error types and handling
163+
✅ Complete platform support with #[cfg]
164+
✅ Follow established patterns in codebase
165+
✅ Update documentation with code changes
166+
167+
## Getting Help
168+
- Review existing code patterns in the codebase
169+
- Check `docs/` for architectural guidance
170+
- Refer to `ref_docs/` for development plans
171+
- Review `to-dos/` for phase-specific requirements
172+
- Consult IRC protocol specs in `docs/specs/`
173+
174+
When in doubt, prioritize:
175+
1. Memory safety and Rust idioms
176+
2. Complete implementation over partial solutions
177+
3. Cross-platform compatibility
178+
4. Protocol compliance
179+
5. Code quality and documentation

0 commit comments

Comments
 (0)