[mbutrovich]

Which issue does this PR close?

• N/A.

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).

Are these changes tested?

• N/A.

AI Disclosure

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

[kevinjqliu]

LGTM

seems like an overall improvement. im curious if you have seem agents already behaving in ways that needs this kind of steering

[kevinjqliu]

should we also mention https://github.com/apache/iceberg-rust/blob/main/crates/iceberg/public-api.txt ? which is used to show diffs on prs regarding public api changes

[kevinjqliu]

i see we already mention this in the lines above

• Use the narrowest visibility that works. Make items pub only when they
  are part of the API the change intends to expose. Run
  make generate-public-api to update each crate's public-api.txt, and
  check its diff for API growth.

[kevinjqliu]

should we be prescriptive here? or just mention something like "evaluate if the api needs to be public and whether it matches existing abstractions. must justify its existence to add a public api"

idk if this helps, this is just the way I talk to my agent 🤷

[mbutrovich]

should we be prescriptive here? or just mention something like "evaluate if the api needs to be public and whether it matches existing abstractions. must justify its existence to add a public api"

I opened the section with your wording. I kept the specific rules as examples, because they come from review feedback that keeps repeating (derives as API, constructors that need table context, growing parameter lists). I'm happy to drop any of them if they read as too narrow.

[mbutrovich]

seems like an overall improvement. im curious if you have seem agents already behaving in ways that needs this kind of steering

I've definitely found myself pushing back in reviews asking why things are made pub (seemingly by default), but also seeing it a lot in DataFusion and arrow-rs which have more strict API stability and deprecation policies. While iceberg-rust hasn't made that explicit, I'd at least encourage API mindfulness for downstream consumers.

[blackmwk]

Thanks @mbutrovich for this pr!

[blackmwk]

seems like an overall improvement. im curious if you have seem agents already behaving in ways that needs this kind of steering

I've definitely found myself pushing back in reviews asking why things are made pub (seemingly by default), but also seeing it a lot in DataFusion and arrow-rs which have more strict API stability and deprecation policies. While iceberg-rust hasn't made that explicit, I'd at least encourage API mindfulness for downstream consumers.

+1, I'm always cautious about pub api changes, and I'm also quite careful in review to make an api public.