Skip to content

docs: allow justified slower shapes in expression optimizations, add code guidelines - #7539

Merged
andygrove merged 2 commits into
apache:mainfrom
mbutrovich:agents-api-stability-perf
Nov 16, 2026
Merged

andygrove merged 2 commits into
apache:mainfrom
mbutrovich:agents-api-stability-perf

Conversation

@mbutrovich

@mbutrovich mbutrovich commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Which issue does this PR close?

N/A.

Rationale for this change

What changes are included in this PR?

  • Adding some guidance based on recurring themes I am seeing across arrow-rs, iceberg-rust, and DataFusion (and its subprojects like datafusion-iceberg and Comet).

How are these changes tested?

N/A.

AI Disclosure

Claude Sonnet helped draft this, but I stand by the content.

@mbutrovich mbutrovich changed the title docs: allow justified slower shapes in expression optimizations docs: allow justified slower shapes in expression optimizations, add code guidelines Nov 6, 2026
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 6, 2026

@comphead comphead left a comment

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.

The new rule reads consistently across the guide, AGENTS.md and the three files under .ai/skills. One gap it leaves in what gets recorded after merge.

nulls but 30% slower with dense nulls costs the many real columns that have dense nulls, so either
gate the fast path behind a runtime check that picks the right path per batch, or do not submit it.
A Comet optimization PR was closed for exactly this reason. A claim that a shape is rare needs
evidence about real workloads, not an assertion.

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.

Now that a merged optimization can make a shape slower, could "Record the performance audit" below ask for that too? Its template records the technique, the speedup, the PR and the benchmark, so the audit entry, which is what the next person tuning the expression reads, would not show that a shape was traded away or why. A clause such as "and any shape that got slower, with its cost" in the template, plus the same in the PR conventions' Testing line, would keep the justification next to the history. Two existing entries in expression-audits/conversion_funcs.md already say "no regression on any shape", so the line has room for it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks, added. The audit template's guidance in optimizing_expressions.md and step 9 of the optimize-comet-expression skill now ask for any shape that got slower with its cost, and the PR conventions' Testing line asks for the cost and justification.

@andygrove andygrove left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The PR backlog is huge and the maintainers don't have the bandwidth to review them all, so here is an automated review. Feel free to ignore it.

Thanks for tightening the guidance here. The slower-shape rule reads consistently across optimizing_expressions.md, optimize-comet-expression/SKILL.md, review-comet-pr/SKILL.md and review-comet-expression-pr/SKILL.md, and I did not find a leftover "no regression" statement elsewhere under .ai or the contributor guide. The gap comphead raised about the audit entry template is the one I would also want closed.

One new line in AGENTS.md is broader than the page it points to. The config bullet says renames and removals "need a deprecated alias and a major release". config_conventions.md says in "Renaming an Existing Config" that keys in the testing category and keys marked internal() are exempt from the versioning policy and may be renamed outright, with no alias. An agent following the bullet literally would add withAlternative aliases for those keys. Could the bullet say that the rule applies to keys covered by the versioning policy, and link to that section?

@mbutrovich

Copy link
Copy Markdown
Contributor Author

Could the bullet say that the rule applies to keys covered by the versioning policy, and link to that section?

Thanks, done. The bullet now says the alias and major release apply to keys covered by the versioning policy, states that testing and internal() keys are exempt, and links to Renaming an Existing Config.

@andygrove andygrove left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks @mbutrovich

@andygrove
andygrove enabled auto-merge November 16, 2026 14:37
@andygrove
andygrove added this pull request to the merge queue Nov 16, 2026
Merged via the queue into apache:main with commit 6795d42 Nov 16, 2026
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants