Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (103 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

138 lines (103 loc) · 4.82 KB

Contributing to High Boy Firmware

Thank you for your interest in contributing to High Boy! We welcome contributions from everyone. This document provides guidelines and instructions to help you get started.

Getting Started

1. Cloning the Repository

Clone the repository and its submodules recursively to ensure you have all dependencies:

git clone --recursive https://github.com/HighCodeh/TentacleOS.git
cd TentacleOS

2. Prerequisites

Tool Version Purpose
ESP-IDF v5.3+ Build system and SDK
clang-format any Code formatting (enforced by pre-commit hook)
Git 2.9+ Required for core.hooksPath support

Install ESP-IDF and ensure your environment is set up:

. $HOME/esp/esp-idf/export.sh

Install clang-format:

# Arch / Manjaro
sudo pacman -S clang

# Ubuntu / Debian
sudo apt install clang-format

# macOS
brew install clang-format

3. Compiling

The project supports multiple hardware targets. Navigate to the specific firmware directory for your target:

ESP32-C5

cd firmware_c5
idf.py set-target esp32c5
idf.py build

ESP32-P4

cd firmware_p4
idf.py set-target esp32p4
idf.py build

(Note: In the /tools directory, there is a .sh file responsible for automatic building and flashing.)

Development Workflow

Coding Style & Conventions

All coding rules, naming conventions, formatting, error handling and reference examples are in CODING_STANDARDS.md. Read it before submitting code.

Commit Conventions

We use Conventional Commits. This is enforced by a git hook — commits that don't follow the format will be rejected.

Format: <type>(<scope>): <description>

Type Description Version Impact
feat New feature Minor bump (0.X.0)
fix Bug fix Patch bump (0.0.X)
perf Performance improvement Patch bump (0.0.X)
docs Documentation only No bump
style Code style (formatting, etc.) No bump
refactor Code refactoring No bump
test Adding or updating tests No bump
chore Maintenance tasks No bump
ci CI/CD changes No bump
build Build system changes No bump
revert Reverting a previous commit No bump

Breaking changes (major version bump) are indicated by adding ! before the colon:

feat(spi)!: redesigned bridge protocol
fix!: changed public API return types

Examples:

feat(subghz): add waterfall visualization
fix(spi): corrected timeout on bridge init
feat(bt)!: redesigned BLE protocol
chore: cleanup unused imports
refactor(ota): simplified update flow

Automatic Versioning

This project uses Semantic Versioning with fully automated version bumps via semantic-release.

  • Versioning is handled entirely by GitHub Actions — contributors do not need to manage versions manually.
  • When a PR is merged into main, the CI pipeline analyzes commit messages, determines the version bump, creates a git tag, generates a changelog, and publishes a GitHub Release with the firmware binaries.
  • Just write your commits following the Conventional Commits format and the rest is automatic.

Git Hooks Setup

After cloning the repository, run the setup script to install the required git hooks:

./tools/setup.sh

This configures git to use the project hooks (.githooks/). The hooks include:

  • pre-commit — checks code formatting with clang-format
  • commit-msg — validates Conventional Commits format

Continuous Integration (CI)

We use GitHub Actions to automatically build the project for all supported targets upon every push and Pull Request.

  • Status Checks: All CI builds must pass before a Pull Request can be merged.
  • Blocked Merges: If any build fails, the merge will be blocked until the issues are resolved.

Pull Request Process

  1. Create a Branch: Create a feature or bugfix branch from dev or main.
  2. Commit Changes: Use conventional commit messages.
  3. Verify Build: Ensure the project compiles locally for your target.
  4. Push & PR: Push to your fork and create a Pull Request against the dev branch.
  5. CI Validation: Wait for GitHub Actions to complete the build verification.
  6. Review: At least one maintainer must review and approve your PR before merging.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct.

Communication

For questions or discussions, please use GitHub Issues or join our community channels (Discord / Telegram).