Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
390 lines (282 loc) · 9.58 KB

CONTRIBUTING.md

File metadata and controls

390 lines (282 loc) · 9.58 KB

Contributing to clangd-kernel-helper

English | 中文

English

First off, thank you for considering contributing to clangd-kernel-helper! It's people like you that make this tool better for everyone.

🌟 Ways to Contribute

There are many ways you can contribute to this project:

  • 🐛 Report bugs: Found a bug? Open an issue with detailed information
  • 💡 Suggest features: Have an idea? Share it in the issues
  • 📖 Improve documentation: Help make the docs clearer and more comprehensive
  • 🔧 Submit code: Fix bugs or implement new features
  • 🌍 Add translations: Help translate the documentation to other languages
  • ⭐ Spread the word: Star the project and tell others about it

📋 Before You Start

  1. Check existing issues: Your issue or idea might already be discussed
  2. Read the documentation: Make sure you understand how the tool works
  3. Test your changes: Ensure your changes work with different kernel versions

🐛 Reporting Bugs

When reporting bugs, please include:

  • Description: Clear description of the problem
  • Environment:
    • Linux kernel version
    • Python version
    • Architecture (ARM, ARM64, x86_64, etc.)
    • Cross-compiler version
  • Steps to reproduce: Detailed steps to reproduce the issue
  • Expected behavior: What you expected to happen
  • Actual behavior: What actually happened
  • Error messages: Full error messages or logs

Example:

**Bug Description**
The script fails to extract CONFIG_* macros from autoconf.h

**Environment**
- Kernel: Linux 5.15.0
- Python: 3.9.7
- Arch: arm64
- Cross-compiler: aarch64-linux-gnu-gcc 9.4.0

**Steps to Reproduce**
1. Clone the kernel repository
2. Build with `make defconfig && make -j8`
3. Run `./clangd-kernel-helper --with-kernel`

**Expected**
Should extract 900+ CONFIG_* macros

**Actual**
Only extracted 10 macros

**Error Message**
[paste error message here]

💡 Suggesting Features

When suggesting features, please include:

  • Use case: What problem does this solve?
  • Proposed solution: How would you like this to work?
  • Alternatives: Have you considered other approaches?
  • Examples: Provide examples if possible

🔧 Submitting Code

Development Setup

  1. Fork the repository

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/clangd-kernel-helper.git
cd clangd-kernel-helper

  3. Create a branch for your changes:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Code Style

  • Follow PEP 8 for Python code
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Keep functions focused and concise

Testing

Before submitting, test your changes with:

  • Different kernel versions (4.x, 5.x, 6.x)
  • Different architectures (ARM, ARM64, x86_64)
  • With and without --with-kernel flag
  • Edge cases (empty directories, missing files, etc.)

Commit Messages

Write clear commit messages:

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Fix bug" not "Fixes bug")
  • First line should be a brief summary (50 chars or less)
  • Add detailed description if needed

Examples:

Good:
✅ Add support for RISC-V architecture
✅ Fix path resolution for relative includes
✅ Improve error handling in config extraction

Bad:
❌ Update code
❌ Fixed stuff
❌ Changes

Pull Request Process

  1. Update documentation if needed (README, comments, etc.)

  2. Make sure your code follows the style guide

  3. Test thoroughly

  4. Push to your fork:

    git push origin feature/your-feature-name

  5. Open a Pull Request with:

    • Clear title: Summarize the change
    • Description: Explain what and why
    • Related issues: Link to any related issues
    • Testing: Describe how you tested

  6. Wait for review and address feedback

🌍 Translating Documentation

We welcome translations! To add a new language:

  1. Create a new README file: README_[language_code].md

    • Example: README_ja.md for Japanese
    • Example: README_de.md for German

  2. Translate the content while keeping:

    • Code blocks unchanged
    • Links working
    • Same structure

  3. Update the language switcher in all README files:

    [English](README.md) | [中文](README_zh.md) | [Your Language](README_xx.md)

  4. Submit a PR with your translation

📝 Documentation Guidelines

When improving documentation:

  • Be clear and concise
  • Use examples where helpful
  • Keep it beginner-friendly
  • Update all language versions if possible

❓ Questions?

If you have questions:

📜 Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • Help others learn and grow

中文

首先，感谢你考虑为 clangd-kernel-helper 做出贡献！正是像你这样的人让这个工具变得更好。

🌟 贡献方式

你可以通过多种方式为这个项目做出贡献：

  • 🐛 报告 bug：发现 bug？请开一个详细的 issue
  • 💡 提出功能建议：有想法？在 issues 中分享
  • 📖 改进文档：帮助让文档更清晰、更全面
  • 🔧 提交代码：修复 bug 或实现新功能
  • 🌍 添加翻译：帮助翻译文档到其他语言
  • ⭐ 传播项目：给项目加星并告诉其他人

📋 开始之前

  1. 检查现有 issues：你的问题或想法可能已经被讨论过
  2. 阅读文档：确保你理解工具的工作原理
  3. 测试你的更改：确保你的更改适用于不同的内核版本

🐛 报告 Bug

报告 bug 时，请包含：

  • 描述：清晰描述问题
  • 环境信息：
    • Linux 内核版本
    • Python 版本
    • 架构（ARM, ARM64, x86_64 等）
    • 交叉编译器版本
  • 重现步骤：详细的重现步骤
  • 期望行为：你期望发生什么
  • 实际行为：实际发生了什么
  • 错误信息：完整的错误信息或日志

示例：

**Bug 描述**
脚本无法从 autoconf.h 提取 CONFIG_* 宏

**环境信息**
- 内核：Linux 5.15.0
- Python：3.9.7
- 架构：arm64
- 交叉编译器：aarch64-linux-gnu-gcc 9.4.0

**重现步骤**
1. 克隆内核仓库
2. 使用 `make defconfig && make -j8` 编译
3. 运行 `./clangd-kernel-helper --with-kernel`

**期望结果**
应该提取 900+ 个 CONFIG_* 宏

**实际结果**
只提取了 10 个宏

**错误信息**
[在此粘贴错误信息]

💡 提出功能建议

提出功能建议时，请包含：

  • 使用场景：这解决了什么问题？
  • 建议方案：你希望如何实现？
  • 替代方案：你考虑过其他方法吗？
  • 示例：如果可能，请提供示例

🔧 提交代码

开发环境设置

  1. Fork 这个仓库

  2. 克隆你的 fork：

    git clone https://github.com/YOUR_USERNAME/clangd-kernel-helper.git
cd clangd-kernel-helper

  3. 为你的更改创建分支：

    git checkout -b feature/你的功能名
# 或
git checkout -b fix/你的bug修复

代码风格

  • 遵循 PEP 8 Python 代码规范
  • 使用有意义的变量和函数名
  • 为复杂逻辑添加注释
  • 保持函数专注和简洁

测试

提交前，请测试你的更改：

  • 不同的内核版本（4.x, 5.x, 6.x）
  • 不同的架构（ARM, ARM64, x86_64）
  • 使用和不使用 --with-kernel 标志
  • 边缘情况（空目录、缺失文件等）

提交信息

编写清晰的提交信息：

  • 使用现在时（"Add feature" 而不是 "Added feature"）
  • 使用祈使语气（"Fix bug" 而不是 "Fixes bug"）
  • 第一行应该是简短摘要（50 字符以内）
  • 如需要，添加详细描述

示例：

好的：
✅ 添加 RISC-V 架构支持
✅ 修复相对路径 include 的路径解析
✅ 改进配置提取中的错误处理

不好的：
❌ 更新代码
❌ 修复了一些东西
❌ 更改

Pull Request 流程

  1. 如需要，更新文档（README、注释等）

  2. 确保你的代码遵循风格指南

  3. 彻底测试

  4. 推送到你的 fork：

    git push origin feature/你的功能名

  5. 开启 Pull Request，包含：

    • 清晰的标题：总结更改
    • 描述：解释做了什么和为什么
    • 相关 issues：链接到相关 issues
    • 测试：描述如何测试

  6. 等待审查并处理反馈

🌍 翻译文档

我们欢迎翻译！要添加新语言：

  1. 创建新的 README 文件：README_[语言代码].md

    • 例如：README_ja.md 日语
    • 例如：README_de.md 德语

  2. 翻译内容，同时保持：

    • 代码块不变
    • 链接有效
    • 相同的结构

  3. 更新所有 README 文件中的语言切换器：

    [English](README.md) | [中文](README_zh.md) | [你的语言](README_xx.md)

  4. 提交包含你的翻译的 PR

📝 文档指南

改进文档时：

  • 清晰简洁
  • 适当使用示例
  • 保持对初学者友好
  • 如果可能，更新所有语言版本

❓ 有问题？

如果你有问题：

📜 行为准则

  • 尊重和包容
  • 欢迎新手
  • 专注于建设性反馈
  • 帮助他人学习和成长

Thank you for contributing! 感谢你的贡献！ 🎉