apache / apache/arrow-nanoarrow

Define the relationship between nanoarrow and C++

Open
#599 11 comments 0 reactions 0 assignees View on GitHub
Dominant language
C
Stars
249
Forks
68
Avg merge
2d 21h
Merged PRs (30d)
11

Description

Currently it's not explicit what level of C++ is recommended for use in the nanoarrow project. The library itself is of course a minimal API in pure C, but a C++ helper library is packaged alongside and the unit tests are all C++.

This is part of general tension in the project between ergonomics and minimalism of the API. New helper functions are suspect for fear of bloating the API, but this leads to extremely verbose unit tests and code examples.

WRT using unit tests as documentation: although I think it's useful to have complete and self-contained examples of API usage, I think the priority for unit tests should be coverage rather than didactics.

I'd propose:
- we survey the community to find out whether the C++ layer is seriously used or could be left internal
- if the C++ layer **is** widely used, does strict minimalism apply to that as well or can the C++ layer grow more freely?
- document these decision in .rst
- we should write a large body of pure C example code, explicitly freeing up unit tests to be more terse and idiomatic
- perhaps limiting unit tests to C++17, or relying more on the python layer for unit testing
- add DSLs available to the tests allowing schema and data literals to be written concisely

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the C++ helper library, the C++ unit tests, and the Python testing layer, then survey whether the C++ layer is used externally. Record the agreed C++ relationship, minimalism policy, and testing/example guidance in .rst documentation; the work is done when those decisions are documented and the proposed pure C examples or test DSL direction is resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, cpp
Domain
developer-experience, documentation, testing
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.