Skip to content

[github] add copilot instructions #10626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rbb666 merged 1 commit into from
Aug 21, 2025
Merged

[github] add copilot instructions #10626

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 196 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
# GitHub Copilot Instructions for RT-Thread / RT-Thread GitHub Copilot 指南

## Overview / 概述

RT-Thread is a real-time operating system (RTOS) for embedded devices. When working with RT-Thread code, please follow these guidelines to ensure high-quality contributions.

RT-Thread 是一个面向嵌入式设备的实时操作系统（RTOS）。在处理 RT-Thread 代码时，请遵循以下指南以确保高质量的贡献。

## Code Review Guidelines / 代码审查指南

### Language Requirements / 语言要求

When reviewing code, provide feedback in **both English and Chinese** to ensure accessibility for all contributors.

在审查代码时，请同时使用**英文和中文**提供反馈，以确保所有贡献者都能理解。

### Review Focus Areas / 审查重点领域

1. **Real-Time Performance / 实时性能**
- Verify interrupt handling efficiency / 验证中断处理效率
Copy link

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The interrupt handling efficiency guideline is too vague. Consider adding specific criteria such as 'Keep ISR execution time under X microseconds' or 'Avoid blocking operations in ISRs' to provide more actionable guidance.

Suggested change
- Verify interrupt handling efficiency / 验证中断处理效率
- Verify interrupt handling efficiency: Keep ISR execution time under 10 microseconds; avoid blocking operations in ISRs / 验证中断处理效率：确保中断服务程序（ISR）执行时间不超过 10 微秒；避免在 ISR 中使用阻塞操作

Copilot uses AI. Check for mistakes.

2. **Memory Management / 内存管理**
- Detect memory leaks / 检测内存泄漏
- Verify proper memory allocation/deallocation / 验证正确的内存分配/释放
- Check stack usage optimization / 检查栈使用优化

3. **Code Style / 代码风格**
- Follow RT-Thread coding standards / 遵循 RT-Thread 编码标准
- Maintain consistent naming conventions / 保持一致的命名约定
- Ensure proper code comments (not documentation) / 确保适当的代码注释（而非文档）

### Review Comment Format / 审查评论格式

When providing review comments, use the following format:

提供审查评论时，请使用以下格式：

```
[Category/类别]: Brief description / 简要描述

English: Detailed explanation of the issue and suggested improvement.
中文：问题的详细说明和改进建议。

Example/示例:
```c
// Your code example here / 你的代码示例
```
```

### Common Issues to Check / 常见问题检查

1. **Resource Management / 资源管理**
- Unclosed file handles / 未关闭的文件句柄
- Unreleased semaphores / 未释放的信号量
- Memory not freed after malloc / malloc 后未释放内存

2. **Error Handling / 错误处理**
- Missing error checks / 缺少错误检查
- Improper error propagation / 不当的错误传播
- Silent failures / 静默失败

3. **Performance Concerns / 性能问题**
- Unnecessary polling / 不必要的轮询
- Inefficient algorithms in ISRs / ISR 中的低效算法
- Excessive context switching / 过度的上下文切换

### Severity Levels / 严重程度级别

- **🔴 Critical/严重**: Issues that may cause system crashes or data corruption / 可能导致系统崩溃或数据损坏的问题
- **🟠 Major/主要**: Significant bugs or performance issues / 重大错误或性能问题
- **🟡 Minor/次要**: Code style or minor optimization opportunities / 代码风格或次要优化机会
- **🟢 Suggestion/建议**: Best practices or enhancement ideas / 最佳实践或增强建议

## RT-Thread Specific Guidelines / RT-Thread 特定指南

### Kernel Components / 内核组件

When reviewing kernel-related code:
审查内核相关代码时：

- Verify rt_thread structure usage / 验证 rt_thread 结构使用
Copy link

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rt_thread structure usage guideline is incomplete. It should specify what aspects to verify, such as proper initialization, thread priority settings, or stack size validation.

Suggested change
- Verify rt_thread structure usage / 验证 rt_thread 结构使用
- Verify rt_thread structure usage, including:
- Proper initialization of the rt_thread structure / 正确初始化 rt_thread 结构体
- Correct thread priority settings / 正确设置线程优先级
- Appropriate stack size validation / 合理验证栈大小

Copilot uses AI. Check for mistakes.

### Device Drivers / 设备驱动

For device driver reviews:
对于设备驱动审查：

- Ensure proper device registration / 确保正确的设备注册
- Verify I/O operation handling / 验证 I/O 操作处理

### Network Stack / 网络协议栈

When reviewing network code:
审查网络代码时：

- Validate SAL (Socket Abstraction Layer) usage / 验证 SAL（套接字抽象层）使用
- Check protocol implementations / 检查协议实现
- Ensure proper buffer management / 确保正确的缓冲区管理

## Coding Standards / 编码标准

### Object-Oriented Design in C / C语言面向对象设计

1. **Inheritance Pattern / 继承模式**
- First member should be base struct / 第一个成员希望是基类结构体
- Use pointer casting for type conversion / 通过指针强制转换实现类型转换

2. **Polymorphism via ops / 通过ops实现多态**
- Define ops struct with function pointers / 定义包含函数指针的ops结构体
- Share single ops table across instances / 多个实例共享同一ops表

### Naming Conventions / 命名规范

- **Structures / 结构体**: `rt_[name]`
- **Public Functions / 公开函数**: `rt_[class]_[action]`
- **Static Functions / 静态函数**: `_[class]_[action]`
- **Hardware Functions / 硬件函数**: `rt_hw_`
- **Macros / 宏定义**: UPPERCASE (except for local function/variable macros)
Copy link

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exception for 'local function/variable macros' is unclear. Consider providing examples or more specific criteria for when macros should not be UPPERCASE to avoid confusion.

Suggested change
- **Macros / 宏定义**: UPPERCASE (except for local function/variable macros)
- **Macros / 宏定义**: UPPERCASE for global macros. For macros that are local to a single function or file (such as small helpers or inline utilities), lowercase or mixed case may be used.
- **Examples / 示例**:
- Global macro: `#define RT_THREAD_PRIORITY_MAX 32`
- Local macro (inside a function or file): `#define min(a, b) ((a) < (b) ? (a) : (b))`

Copilot uses AI. Check for mistakes.
- **Error Codes / 错误码**: `RT_` + POSIX error code, `RT_EOK` for success

### Object Lifecycle / 对象生命周期

- Provide dual APIs / 提供双模式API:
- `init/detach` for static objects / 用于静态对象
- `create/delete` for dynamic objects / 用于动态对象
- Use reference counting / 使用引用计数
- Return unified error codes / 返回统一错误码

### Code Format / 代码格式

- 4 spaces indentation, no tabs / 4空格缩进，不使用tab
- Braces on separate lines / 大括号独占一行
- Align parameters on line breaks / 参数换行时对齐

## Documentation Standards / 文档标准

### Language and Format / 语言和格式

- Use English for code comments / 所有代码注释使用英文
- Markdown format for documentation / 文档使用Markdown格式
- Prefer Mermaid for diagrams, or PlantUML (hide footbox in sequence diagrams) / 优先使用Mermaid绘图，或PlantUML（时序图隐藏footbox）
Copy link

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The instruction to 'hide footbox in sequence diagrams' is a very specific PlantUML detail that seems out of place in general documentation guidelines. Consider moving this to a more detailed PlantUML style guide or removing it for brevity.

Suggested change
- Prefer Mermaid for diagrams, or PlantUML (hide footbox in sequence diagrams) / 优先使用Mermaid绘图，或PlantUML（时序图隐藏footbox）
- Prefer Mermaid for diagrams, or PlantUML / 优先使用Mermaid绘图，或PlantUML

Copilot uses AI. Check for mistakes.

### Document Structure / 文档结构

1. **Main Level / 主干层**: Overall overview / 整体概述
2. **Branch Level / 分支层**: Module introduction / 子模块介绍
3. **Node Level / 节点层**: Detailed knowledge points / 知识点详解

### Documentation Principles / 文档原则

- Keep structure flat / 保持扁平结构
- Modular organization / 模块化组织
- Clear and concise content / 内容简洁直接
- Complete executable examples / 完整可执行示例

## Best Practices / 最佳实践

1. **Always consider embedded constraints** / **始终考虑嵌入式约束**
- Limited RAM and ROM / 有限的 RAM 和 ROM
- Power consumption / 功耗
- Real-time requirements / 实时要求
- Prefer static allocation / 优先静态分配
- Use memory alignment / 使用内存对齐

2. **Verify on real hardware or at least QEMU** / **尽可能在真实硬件上验证，或至少在QEMU上验证**
- Test on actual hardware when available / 有条件时在真实硬件上测试
- Use QEMU simulation as minimum verification / 至少使用QEMU仿真进行验证
- Consider various BSP configurations / 考虑各种 BSP 配置

3. **Document hardware dependencies** / **记录硬件依赖**
- Specify required peripherals / 指定所需外设
- Note timing constraints / 注意时序约束
- List supported MCU/MPU families / 列出支持的 MCU/MPU 系列

4. **Code Optimization / 代码优化**
- Use `rt_inline` for simple functions / 简单函数使用rt_inline
- Avoid deep nesting / 避免深层嵌套
- Single responsibility per function / 函数功能单一
- Minimize code duplication / 减少代码重复

## Contributing / 贡献

When suggesting improvements:
提出改进建议时：

1. Provide clear, actionable feedback / 提供清晰、可操作的反馈
2. Include code examples when possible / 尽可能包含代码示例
3. Reference RT-Thread documentation / 引用 RT-Thread 文档
4. Consider backward compatibility / 考虑向后兼容性

## References / 参考资料

- [RT-Thread Documentation](https://www.rt-thread.io/document/site/)
- [RT-Thread Coding Style Guide](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_en.md)
- [RT-Thread 文档中心](https://www.rt-thread.org/document/site/)
- [RT-Thread 编码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md)