Deprecate Fields::remove and Schema::remove

[tustvold]

Which issue does this PR close?

Closes #.

Rationale for this change

These were added in #4959 but in hindsight we should just direct users to SchemaBuilder. This keeps the API of Schema and Fields consistently immutable.

What changes are included in this PR?

Are there any user-facing changes?

[alamb]

I think we should leave these APIs in place.

While they may be redundant, I think they are much easier to find initially for someone who just wants to remove a field

The mental overhead of figuring out that "I want to remove a field" to "so therefore I should make a builder, call remove, and then call build" I think is pretty high for casual users. I realize this is an opinion / judgement call

Perhaps instead of making this deprecated you can add a note to the documentation saying "You should use SchemaBuilder instead" and provide an example

[tustvold]

If there were multiple such methods on Fields I might agree, but as it stands these methods just create confusion as it isn't immediately obvious that they aren't modifying in place.

There is a fairly prominent doc comment pointing people to SchemaBuilder already

https://docs.rs/arrow-schema/latest/arrow_schema/struct.Fields.html

[alamb]

Here is the PR that aded the API in the first place: #4964

[alamb]

FYI @Folyd

[alamb]

If there were multiple such methods on Fields I might agree, but as it stands these methods just create confusion as it isn't immediately obvious that they aren't modifying in place.

There is a fairly prominent doc comment pointing people to SchemaBuilder already

https://docs.rs/arrow-schema/latest/arrow_schema/struct.Fields.html

I agree that looks like good enough documentation

[Folyd]

Thanks for letting me know. @alamb ❤️