Skip to content

docs: explain input types, casts and ANSI mode in the contributor guide - #360

Merged
andygrove merged 2 commits into
apache:mainfrom
andygrove:docs-cast-coercion-guidelines
Nov 18, 2026
Merged

andygrove merged 2 commits into
apache:mainfrom
andygrove:docs-cast-coercion-guidelines

Conversation

@andygrove

@andygrove andygrove commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Which issue does this PR close?

Rationale for this change

#89, #304, #345 and #350 added a shared way to declare a function's input types, find a common type, cast a value and read ANSI mode. CONTRIBUTING.md does not mention any of them, so a new function is likely to hand-write a Signature, call Arrow's cast, or take a bool for ANSI mode instead.

What changes are included in this PR?

  • A new "Input types, casts and ANSI mode" section in CONTRIBUTING.md. It says when to use SparkInputTypes, the rules in type_coercion.rs, spark_cast() and EvalMode, and points to the module docs for details.
  • The audit skill's "Signature and coercion" and "ANSI handling" checks now point at the guide.

The section says that SparkInputTypes only chooses target types and that spark_cast() returns "not implemented" for casts that are not ported yet (#88). I kept that wording on purpose, so it can be relaxed as the cast port progresses.

Are these changes tested?

Documentation only. I checked each name, path and example against apache/main (sha2.rs, parse_url.rs, array_position.rs, implicit_cast.rs, type_coercion.rs, eval_mode.rs, cast/mod.rs).

Are there any user-facing changes?

No.

This PR was written with the help of an LLM (Claude Code).

Describe SparkInputTypes, the common-type rules, spark_cast and EvalMode, which
were added in apache#89, apache#304, apache#345 and apache#350, and point the audit skill at them.
Point to the module docs instead of restating them, and shorten the audit
skill text to a pointer.
@andygrove
andygrove marked this pull request as ready for review November 18, 2026 18:06
@andygrove

Copy link
Copy Markdown
Member Author

cc @shehabgamin

is already threaded through `ScalarFunctionArgs`, so the implementation reads
it directly:
is already threaded through `ScalarFunctionArgs`. Prefer an `EvalMode` over a
`bool` (see `CONTRIBUTING.md`), as `parse_url` and `try_parse_url` do:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might have to make this a little bit stricter to make eval mode compulsory (at least in the top level function)

@andygrove
andygrove merged commit 6c2d887 into apache:main Nov 18, 2026
8 checks passed
@andygrove
andygrove deleted the docs-cast-coercion-guidelines branch November 18, 2026 19:50
@andygrove

Copy link
Copy Markdown
Member Author

Thanks @coderfender

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants