I want to take a second here to gripe about a change made to the
text/encoding package, which changed the return types of the Encoding
NewDecoder and NewEncoder methods — this change was done recently. These
methods used to simply return a Transformer, but now instead they return a
pointer to a structure that wraps the Transformer.

The new API is definitely “cleaner”, so I can understand where the desire
for a change came from.

But this API change was somewhat gratuitous, and it broke code in the
field. My encoding package, and all of its consumers (which included
tcell, govisor, proxima5, etc.) broke. I’m not sure I know all of my
downstream consumers — that’s the beauty of github. :-)

At this point I’ve fixed my encoding package to operate with the new API,
so that’s fine. (Don’t change it back — that would only make matters worse
at this point.)

But there is a lesson here that I’d like those working in the “official”
golang repos (and I consider golang.org/x/* to mostly be official) - please
be *careful* about changes to the API — adding methods to interfaces and
changing method signatures can have far reaching implications.

Stable APIs matter.

If you don’t think an API is mature enough to be “stable”, maybe it doesn’t
belong in the golang.org/x repo yet. Or at the very least let’s label it
clearly so that folks who start consuming APIs don’t suffer surprise
breakage later. I know that if you tell me an interface is “unstable” or
“experimental”, I’ll use more caution in using it, and maybe even avoid it
for work that needs to be able to rely on stable interfaces.

The lack of API versioning in golang just exacerbates this.

I’m not sure that API versioning would *fix* it, but I think some extra
caution in preserving API stability is warranted.

Thank you for your kind attention and care in preserving API stability
going forward.

  - Garrett

You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Search Discussions

Discussion Posts

Follow ups

Related Discussions

Discussion Navigation
viewthread | post
posts ‹ prev | 1 of 5 | next ›
Discussion Overview
groupgolang-nuts @
postedDec 15, '15 at 9:42p
activeDec 18, '15 at 11:39p



site design / logo © 2022 Grokbase