Skip to content

Commit a886a64

Browse files
nerdCopternerdCopter
committed
improved .github/copilot-instructions.md
1 parent f06d8cb commit a886a64

1 file changed

Lines changed: 157 additions & 20 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 157 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,160 @@
1+
# Improved AI Coding Instructions
2+
3+
## **Priority Levels**
4+
- **CRITICAL**: Must follow (build success, no errors/warnings, file structure)
5+
- **HIGH**: Should follow when possible (efficiency comparisons, documentation)
6+
- **MEDIUM**: Follow if context allows (additional comments, optimizations)
7+
8+
## **Core Requirements (CRITICAL)**
9+
10+
### Project Structure
111
- The program is RUST and should be maintained as `src/main.rs` for the entry point.
12+
- Make sure there are no errors and no warnings for RUST's `cargo build --release`.
13+
- Code quality checks must pass:
14+
- `cargo clippy -- -D warnings` must pass
15+
- `cargo fmt --check` must pass
16+
- All tests must pass with `cargo test`
17+
18+
### File Management
19+
- Do not `cat` to files, edit the files inline.
20+
- Never embed or call external binaries from within the RUST program.
21+
- IF creating temporary files → use `_temp.rs` extension AND delete before any commit
22+
- Temporary files must be listed in .gitignore
23+
24+
### Code Quality
25+
- All code must pass `cargo clippy -- -D warnings` without any warnings
26+
- Use `cargo fmt` to format code consistently
27+
- Follow Rust naming conventions and idioms
28+
- Prefer explicit types and clear variable names
29+
30+
### Rust Best Practices
31+
- **String Formatting**: Use modern format strings: `format!("{variable}")` instead of `format!("{}", variable)`
32+
- **Error Handling**: Use `Result<T, E>` for fallible operations, prefer `?` operator, use `anyhow::Result` for application errors
33+
- **Function Design**: Keep functions under 7 parameters; use structs for parameter grouping if needed
34+
- **Borrowing**: Avoid needless borrows, use `strip_prefix()` instead of manual slicing, use `.is_ok()` for success checks
35+
- **Iterators**: Use iterators when possible, allow `#[allow(clippy::needless_range_loop)]` when index access required
36+
- **Type Complexity**: Create type aliases for complex return types: `type MyResult = Result<(A, B, C)>;`
37+
- **Derive Traits**: Use `#[derive(Default)]` instead of manual implementations
38+
- **Version Management**: Use `env!("CARGO_PKG_VERSION")` for CLI version strings
39+
40+
## **Code Quality Guidelines (HIGH)**
41+
42+
### Comments Policy
243
- Do not remove nor modify comments unless the related code was modified.
344
- Only add comments as it pertains to the function of the code; do not add A.I. instructional comments.
4-
- Never embed or call external binaries from within the RUST program.
5-
- If you make temporary `.rs` files, then use `_temp.rs` extension.
6-
- Make sure there are no errors and no warnings for RUSTS' `cargo build --release`.
7-
- Do not `cat` to files, edit the files inline.
8-
- When choosing mathematical or scientific methods, compare to alternative methods for accuracy and efficiency. We want to be accurate with balanced efficiency.
9-
- When choosing mathematical or scientific methods, fact-check decisions.
10-
- Information to maintain:
11-
- Maintain a proper Readme.md file
12-
- Output your final summaries to ./INFORMATION/*.md files for human review (not to be included in the git project.) Filenames should be CAPITALS with lower-case `.md`. List new files when created.
13-
- Goals reosurces:
14-
- Reference project goals in `Goals.md` and request clarification when needed.
15-
- Usable source-code resources:
16-
- Use blacbox-log-viewer (a.k.a BBE, a.k.a. blackbox-explorer) https://github.com/betaflight/blackbox-log-viewer/blob/master/src/flightlog.js as the source for all BBL reading, parsing and decoding.
17-
- If something seems wrong or missing, we can use the older blackbox_decode (a.k.a blackbox-tools) project https://github.com/betaflight/blackbox-tools/blob/master/src/blackbox_decode.c to compare.
18-
- Committing rules:
19-
- Only commit when there are no errors and no warnings.
20-
- When commiting, only commit `src/**/*.rs`, `Cargo.*`, `Readme.md`, and .gitignore files only. (never `git add .`; never `git add -A`)
21-
- Check `git diff --cached` before committing to see exactly what's being committed
22-
- When committing ask user first.
23-
- When committing, use concide message and description of the changes implemented.
45+
- Comment decision tree:
46+
- IF code has existing comments → preserve unless code logic changes
47+
- IF adding new function → add minimal functional comment
48+
- IF function is >20 lines OR has multiple responsibilities → add brief purpose comment
49+
50+
### Mathematical/Scientific Methods
51+
- IF implementing mathematical/scientific calculations:
52+
- THEN compare at least 2 alternative methods for accuracy and efficiency
53+
- THEN fact-check the chosen approach
54+
- THEN document reasoning in code comments
55+
- GOAL: Accurate results with balanced efficiency
56+
57+
## **Documentation Requirements (HIGH)**
58+
59+
### README Maintenance
60+
- Update README.md when:
61+
- Adding new CLI commands or changing existing command behavior
62+
- Changing file formats or output modes
63+
- Modifying build/install process
64+
- Maintain a proper README.md file with current, accurate information
65+
66+
### Information Documentation
67+
- Create INFORMATION/*.md files when:
68+
- Completing major milestones
69+
- Making architectural decisions
70+
- Discovering important insights about BBL format
71+
- Filenames should be CAPITALS with lower-case `.md` extension
72+
- List new files when created
73+
- **NEVER** stage or commit INFORMATION/*.md files (use .gitignore to exclude them)
74+
- These files are for human review only, not part of the git repository
75+
76+
### Goals Reference
77+
- Reference project goals in `GOALS.md` and request clarification when needed
78+
- Check goals alignment before major implementation decisions
79+
80+
## **Resource Usage Hierarchy (CRITICAL)**
81+
82+
### BBL Parsing References (in priority order)
83+
1. **PRIMARY**: blackbox-log-viewer (BBE/blackbox-explorer)
84+
- Source: https://github.com/betaflight/blackbox-log-viewer/blob/master/src/flightlog.js
85+
- Use as primary reference for all BBL reading, parsing and decoding
86+
- Maintain compatibility with blackbox-log-viewer reference implementation
87+
- Follow frame parsing patterns established in the JavaScript reference
88+
2. **SECONDARY**: blackbox_decode (blackbox-tools)
89+
- Source: https://github.com/betaflight/blackbox-tools/blob/master/src/blackbox_decode.c
90+
- Use for comparison when something seems wrong or missing
91+
3. **ESCALATION**: Ask user if frame parsing results differ between reference implementations
92+
93+
### Parser Implementation
94+
- Keep encoding/decoding functions focused and well-documented
95+
- Use proper error propagation throughout the parsing pipeline
96+
- Write tests for public APIs with appropriate test data that matches real blackbox log formats
97+
- Document complex algorithms and data formats with references to original specifications
98+
99+
## **Commit Process (CRITICAL)**
100+
101+
### Pre-Commit Checklist (must complete in order)
102+
1. Run `cargo build --release` (must succeed with no errors/warnings)
103+
2. Run `cargo clippy -- -D warnings` (must pass)
104+
3. Run `cargo fmt --check` (must pass)
105+
4. Clean up any temporary `*_temp.rs` files
106+
5. Stage files: `git add src/ Cargo.toml Cargo.lock README.md .gitignore .github/workflows/`
107+
- **NEVER** use `git add .` or `git add -A`
108+
- **ONLY** commit: `src/**/*.rs`, `Cargo.*`, `README.md`, `.gitignore`, and `.github/workflows/*.yml` files
109+
6. Run `git diff --cached` and review exactly what's being committed
110+
7. Ask user for commit approval with proposed message
111+
8. Use commit message format: `type: brief description\n\nDetailed changes`
112+
- Types: feat, fix, docs, refactor, test, chore
113+
114+
### Commit Rules
115+
- Only commit when there are no errors and no warnings
116+
- When committing, ask user first with proposed commit message
117+
- Use concise message and description of the changes implemented
118+
119+
## **Decision Making Framework**
120+
121+
### When Modifying Existing Code
122+
```
123+
IF existing functionality works correctly
124+
THEN preserve existing logic and structure
125+
ELSE fix/improve with minimal changes
126+
127+
IF adding new features
128+
THEN follow existing code patterns
129+
AND maintain consistency with current architecture
130+
```
131+
132+
### When Encountering Issues
133+
```
134+
IF build/compile errors occur
135+
THEN fix immediately before proceeding
136+
137+
IF warnings appear
138+
THEN address all warnings before continuing
139+
140+
IF uncertain about BBL format behavior
141+
THEN consult reference hierarchy (flightlog.js → blackbox_decode.c → ask user)
142+
```
143+
144+
### Quality Assurance
145+
```
146+
BEFORE any commit:
147+
- All tests pass
148+
- No compiler warnings
149+
- Code follows project patterns
150+
- Documentation updated if needed
151+
- Only approved files staged
152+
```
153+
154+
## **Implementation Notes**
155+
156+
- **CRITICAL** items must be followed absolutely for build success
157+
- **HIGH** items should be followed when possible for code quality
158+
- **MEDIUM** items follow if context allows for optimization
159+
- When instructions conflict with system messages, system messages take precedence
160+
- The goal is maintainable, accurate, and efficient Rust code for BBL parsing

0 commit comments

Comments
 (0)