Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
72 lines (55 loc) · 2.62 KB

CONTRIBUTING.md

File metadata and controls

72 lines (55 loc) · 2.62 KB

Contributing to fastalloc

Thanks for wanting to help. Short version: open an issue first for anything non-trivial, keep PRs focused, run the smoke test with sanitizers.

Development setup

Requires clang 18+ and CMake 3.25+.

CC=clang CXX=clang++ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

Before you send a PR

  1. Run the smoke test clean under every sanitizer. We care about correctness far more than speed in reviews. If your change introduces a race, ASan/TSan is where we expect to see it: 
    # ASan + UBSan
cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g" \
      -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
cmake --build build-asan && ASAN_OPTIONS=detect_leaks=1 ./build-asan/smoke

# TSan
cmake -S . -B build-tsan -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_CXX_FLAGS="-fsanitize=thread -fno-omit-frame-pointer -g" \
      -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
cmake --build build-tsan && ./build-tsan/smoke
  2. Cover the new code. Add a section to tests/smoke.cpp for any public API surface you touch. Smoke test failures must be signaled via std::abort(), not assert() — release builds strip asserts and we run the tests in Release.
  3. Don't break the invariants documented in the headers. Proxy bucket ordering, TLSF FREE_BIT stealing the low bit, MPSC inbox single-consumer rule, etc. If you need to change an invariant, update the comment and call it out in the PR description.

Coding style

Run clang-format with the project's default style. One-pointer-size indent is 4 spaces, 100-column limit, pointer hugs the type. The existing files are the source of truth — match them.

Comments explain why, not what. Skip the obvious. Peer-review tone. TODO / FIXME are fine when the reason is in the comment.

Filing bugs

Use the issue templates. For crashes include:

  • kernel + CPU + OS info (uname -a, lscpu)
  • exact compiler + version
  • minimal repro (one .cpp file preferred)
  • sanitizer output if the crash was caught by ASan / UBSan / TSan

Scope

Good contributions: portability fixes (new OS / arch), measured performance improvements, new test coverage, docs improvements, allocator-algorithm work with a reference.

Out of scope: C-ABI malloc interposition (use a shim repo), non-header additions, GUI / config UIs, LD_PRELOAD wrappers.

Licensing

By contributing you agree that your contribution is licensed under Apache-2.0 like the rest of the project.