Contribution Guide

This guide will help you understand the contribution process, coding standards, and contribution methods for ElenixOS, providing complete guidance for participating in ElenixOS development.

Coding Standards

C Language Coding Standards

Naming Conventions

File names: Use lowercase letters and underscores, e.g., eos_app.c
Function names: Use lowercase letters and underscores, e.g., eos_app_install
Variable names: Use lowercase letters and underscores, e.g., app_id
Constants and macros: Use uppercase letters and underscores, e.g., EOS_APP_DIR
Type names: Use camel case, e.g., script_pkg_t
Static variable names: Use leading underscore + lowercase letters and underscores, e.g., static int _app_count = 0;

Code Style

The project uses clang-format v20 for C/C++ code formatting, with the configuration file .clang-format in the project root. Key rules include:

Indentation: 4 spaces, no tabs
Column limit: 120 characters per line maximum
Brace style: Allman style (braces on separate lines)
Pointer/Reference alignment: Right-aligned, e.g., int *p, int &r
Condition/Loop statements: Space between keyword and opening parenthesis, e.g., if (x), while (x)
Function declarations/definitions: Return type on the same line as function name
Binary operators: Break before non-assignment operators
Consecutive macros/assignments/declarations: No alignment
Blank lines at block start: Not allowed
Maximum consecutive blank lines: 1
Comments: Doxygen-style comments

For detailed rules, see the .clang-format file in the project root.

Example

/**
 * @brief Install application
 * @param eapk_path eapk installation package path
 * @return eos_result_t Installation result
 */
eos_result_t eos_app_install(const char *eapk_path)
{
    // Function implementation
    return EOS_OK;
}

JavaScript Coding Standards

Naming Conventions

Variable names: Use camel case, e.g., appId
Function names: Use camel case, e.g., installApp
Constant names: Use uppercase letters and underscores, e.g., MAX_APP_COUNT
Object properties: Use camel case, e.g., appName

Code Style

Indentation: Use 2 spaces for indentation
Brackets: Left and right brackets on separate lines
Line length: Each line of code should not exceed 80 characters
Comments: Use JSDoc-style comments

Example

/**
 * Install application
 * @param {string} eapkPath - Application package path
 * @returns {number} Installation result
 */
function installApp(eapkPath)
{
    // Function implementation
    return 0;
}

Code Quality Checks

ElenixOS provides a unified code quality check framework via scripts/check.py to ensure code meets project standards.

Check Types

Running a check executes the following four checkers sequentially:

Checker	Name	Description
architecture	Architecture Constraint Check	Validates code against architecture rules, e.g., `jerry_call()` can only be called in specific files, `malloc`/`free` restricted to the port layer
formatting	Code Formatting Check	Uses clang-format v20 to check C/C++ files against `.clang-format` rules
style	Code Style Check	Uses clang-tidy (or custom regex rules) to scan for style issues, such as TODO/FIXME without issue references, forbidden functions (`sprintf`, `gets`, etc.)
static_analysis	Static Analysis	Runs clang-tidy deep analysis (`--checks='*'`) and cppcheck for comprehensive static analysis

Dependency Installation

clang-format / clang-tidy

Ubuntu / Debian:

sudo apt-get install clang-format-20 clang-tidy-20

macOS:
```
brew install llvm@20
```

Windows:

# Option 1: Official installer (recommended)
# Download LLVM-20.x.x-win64.exe from https://github.com/llvm/llvm-project/releases/
# After installation, clang-format.exe is at C:\Program Files\LLVM\bin\

# Option 2: Chocolatey
choco install llvm

# Option 3: Scoop
scoop install llvm

# Option 4: winget
winget install LLVM.LLVM

Verify with clang-format --version in cmd or PowerShell. Since Windows executables don't have versioned names (clang-format-20 vs clang-format), just use clang-format with the --clang-format parameter.

Or build LLVM 20 yourself and ensure clang-format-20 (Unix) or clang-format (Windows) is in your PATH

Python Dependencies

pip install pyyaml

cppcheck (optional, for static analysis)

sudo apt-get install cppcheck      # Ubuntu/Debian
brew install cppcheck              # macOS

Usage

# Run all checks (project integrity check)
python3 scripts/check.py

# Run specific checks (e.g., formatting and architecture only)
python3 scripts/check.py --check fmt,arch

# Run formatting check only
python3 scripts/check.py --check fmt

# Auto-fix formatting issues
python3 scripts/check.py --check fmt --fix

# JSON output (CI mode)
python3 scripts/check.py --json

# List available checkers
python3 scripts/check.py --list-checks

# Specify clang-format path
python3 scripts/check.py --clang-format /usr/bin/clang-format-20

Project Integrity Check

Running scripts/check.py without arguments executes all four checkers as a comprehensive project integrity verification. Please run it before submitting new code to ensure all checks pass.

CI Automation

The project automatically runs code quality checks via GitHub Actions, configured in .github/workflows/check.yml:

Trigger: Automatically runs on push or PR to main or dev branches
Environment: Ubuntu latest
Command: python3 scripts/check.py --json --clang-format clang-format-20
On failure: PRs will be blocked from merging; fix issues based on CI logs

Development Process

Branch Management

ElenixOS uses Git for version control, adopting the following branch management strategy:

main: Main branch, contains stable versions
dev: Development branch, contains latest development code

Development Steps

Fork the project: Fork the project on GitHub to your repository
Clone the project: Clone the forked project to your local repository

git clone https://github.com/your-username/ElenixOS.git

Switch branch: Switch to the dev branch

git checkout dev

Write code: Implement features or fix bugs
Test code: Ensure the code can compile and run normally
Commit code: Commit code to local repository

git add .
git commit -m "feat: New feature"

Push branch: Push the branch to the remote repository

git push origin dev

Create Pull Request: Create a Pull Request on GitHub, describing the functionality or fix

Contribution Process

Contribution Methods

Report issues: Report bugs or feature requests in GitHub Issues
Submit code: Submit code through Pull Request
Improve documentation: Improve project documentation
Test: Test code and provide feedback

Code Review

All submitted code needs to go through code review to ensure code quality and consistency. The focus of code review includes:

Whether the code style conforms to the specifications
Whether the functionality is correctly implemented
Whether the code is secure
Whether the performance is reasonable
Whether the documentation is complete

Commit Specifications

Commit messages should follow the following format:

type(module): subject

body (optional)

Where type can be one of the following:

feat: New feature
fix: Bug fix
docs: Documentation improvement
style: Code style adjustment
refactor: Code refactoring
test: Test code
chore: Build or dependency update

Module is optional and used to specify the module or component of the commit.

Examples:

feat: Add app install feature

Implemented app install feature.

refactor(sni): Refactor sni module

For internationalization, commit messages should be described in English.

Testing

All new features or bug fixes should include corresponding tests. The project employs multiple testing methods:

Unit tests: Written using the project's built-in test framework
Integration tests: Verify correct interaction between modules
Performance tests: Ensure no performance regression on critical paths

Please ensure relevant tests pass before submitting code.

Documentation Writing

Documentation Structure

The documentation repository uses Docusaurus multilingual architecture:

docs/ — Chinese version (Simplified Chinese, primary version)
i18n/en/docusaurus-plugin-content-docs/current/ — English version (translation)

Documentation is written in MDX (Markdown + JSX, Docusaurus framework) format, located in the ElenixOS-Docs repository.

Each document should have only one "main language version" (Chinese), and content in other languages should be translated versions of the document to avoid content inconsistencies caused by independent modifications between multiple languages.

Documentation in different languages should try to maintain a consistent directory structure. We recommend creating matching files for the corresponding language, but this is not mandatory. If translations are temporarily missing, they can be added later (we will continue to improve), and contributors do not need to provide multilingual versions at the time of submission.

Documentation Standards

ElenixOS documentation uses MDX (Markdown + JSX, Docusaurus framework) format and should follow these standards:

Format: Use MDX format (.mdx files), supporting standard Markdown syntax and JSX components
Heading levels: Use clear heading hierarchy — # for page title, ## for main sections, ### for subsections; avoid skipping levels
Code blocks: Use ``` markers and specify the language (e.g., c, javascript, bash) for syntax highlighting
Line length: Recommended to keep lines under 120 characters (not mandatory, but helpful for review)
Charts: Use mermaid syntax for flowcharts, sequence diagrams, etc.
Links: Use relative paths for internal links; be aware of the multilingual directory structure
Code-documentation consistency: Keep documentation synchronized with code implementation to avoid outdated descriptions
React components: Leverage Docusaurus MDX capabilities to use custom components

Community Communication

GitHub Issues: For reporting issues and feature requests

Next Steps

Check Core Modules documentation to understand the core features of the system
Check API Documentation to understand how to use system APIs
Check Development Tools documentation to understand the use of development tools

Welcome to join the ElenixOS development community and contribute your strength to the project!

Coding Standards​

C Language Coding Standards​

Naming Conventions​

Code Style​

Example​

JavaScript Coding Standards​

Naming Conventions​

Code Style​

Example​

Code Quality Checks​

Check Types​

Dependency Installation​

clang-format / clang-tidy​

Python Dependencies​

cppcheck (optional, for static analysis)​

Usage​

Project Integrity Check​

CI Automation​

Development Process​

Branch Management​

Development Steps​

Contribution Process​

Contribution Methods​

Code Review​

Commit Specifications​

Testing​

Documentation Writing​

Documentation Structure​

Documentation Standards​

Community Communication​

Next Steps​

Coding Standards

C Language Coding Standards

Naming Conventions

Code Style

Example

JavaScript Coding Standards

Naming Conventions

Code Style

Example

Code Quality Checks

Check Types

Dependency Installation

clang-format / clang-tidy

Python Dependencies

cppcheck (optional, for static analysis)

Usage

Project Integrity Check

CI Automation

Development Process

Branch Management

Development Steps

Contribution Process

Contribution Methods

Code Review

Commit Specifications

Testing

Documentation Writing

Documentation Structure

Documentation Standards

Community Communication

Next Steps