Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (47 loc) · 2.66 KB

CONTRIBUTING.md

File metadata and controls

56 lines (47 loc) · 2.66 KB
Raw

Contributing to Gingoduino

Thank you for your interest in contributing to Gingoduino.

Reporting Issues

Open an issue with:

  • What you expected
  • What happened
  • Minimal code to reproduce
  • Platform, board, and toolchain version (Arduino IDE / PlatformIO / ESP-IDF)

Code Contributions

  1. Fork the repository
  2. Create a branch (git checkout -b fix/description)
  3. Make your changes
  4. Run host tests: 
    g++ -std=c++11 -I. -Wall -Wextra -Werror \
    -o extras/tests/test_native extras/tests/test_native.cpp
./extras/tests/test_native
  5. Run sanitizers locally: 
    g++ -std=c++11 -I. -Wall -Wextra \
    -fsanitize=address,undefined -fno-sanitize-recover=all -g \
    -o extras/tests/test_native_san extras/tests/test_native.cpp
./extras/tests/test_native_san
  6. Verify zero warnings across compilers: 
    g++   -std=c++11 -I. -Wall -Wextra -Werror -c extras/tests/test_native.cpp -o /dev/null
clang++ -std=c++11 -I. -Wall -Wextra -Werror -c extras/tests/test_native.cpp -o /dev/null
  7. Open a pull request with a clear description

Code Style

  • C++11 strict (-Wall -Wextra -Werror, zero warnings on GCC and Clang)
  • Zero heap -- no malloc, free, new, delete, no std::string, no std::vector. The library targets MCUs with kilobytes of RAM
  • Caller-provided storage -- string-returning methods take (char* buf, uint8_t maxLen); array-returning methods take (T* output, uint8_t maxItems) and return the count actually written
  • FixedStr<N> and FixedArray<T, N> carry capacity at the type level
  • PROGMEM lookup tables on AVR; transparent fallback on non-Arduino targets via gingoduino_config.h
  • Naming: Gingo<Domain> for classes (GingoNote, GingoChord, GingoMIDI2); methods in camelCase; preprocessor macros GINGODUINO_*
  • No feature gates -- every module is always compiled; pay-as-you-go via linker dead-code elimination
  • Every new public method needs a test -- native tests under extras/tests/test_native.cpp
  • No external dependencies -- the library is standalone; transport (UART, USB, BLE) and protocol (UMP dispatch, MIDI-CI) belong to companion libraries (midi2cpp, midi2, Arduino MIDI Library)
  • Comments: explain why, not what. The code should be self-evident.

Commit Messages

  • One purpose per commit
  • Imperative subject line under 72 characters, lowercase, conventional prefix (feat:, fix:, docs:, chore:, test:, refactor:, release:)
  • Optional one-line body describing the rationale, not the change itself
  • Reference issues with Ref #N (issues close when behavior is confirmed by the reporter, not by a commit keyword)