FAQ
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

  • Konstantin Kulikov at Dec 16, 2015 at 5:21 pm
    You can find all of your downstream users using godoc:
    https://godoc.org/github.com/gdamore/tcell?importers
    On Wed, Dec 16, 2015 at 12:42 AM Garrett D'Amore wrote:

    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.
    --
    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.
  • Garrett D'Amore at Dec 16, 2015 at 8:03 pm
    That’s only true for downstreams that have reported on godoc using a public
    repo. It won’t tell you anything at all about internal proprietary
    consumers.
    On Wed, Dec 16, 2015 at 8:32 AM, Konstantin Kulikov wrote:

    You can find all of your downstream users using godoc:
    https://godoc.org/github.com/gdamore/tcell?importers
    On Wed, Dec 16, 2015 at 12:42 AM Garrett D'Amore wrote:

    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.
    --
    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.
  • Florin Patan at Dec 17, 2015 at 1:11 am
    According to the official documentation, https://github.com/golang/go/wiki/SubRepositories, the golang.org/x repos are not required to satisfy any compatibility guarantee that the Go core does. Thus, as the name suggests, these experimental repos might have their API broken every now and then if needed.
    So, while frustrating as it might be for you as end-user, the mistake is on your side, for considering/assuming that they are covered by any sorts of strong guarantees instead of look at the docs / Google searching. P.S. Heads-up, there are packages in Go itself that are stil not covered by the official compatibility promise :-)

    --
    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.
  • Nigel Tao at Dec 18, 2015 at 11:39 pm
    +mpvl
    On Wed, Dec 16, 2015 at 8:42 AM, Garrett D'Amore wrote:
    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.
    Yeah, the next time we break API for something under golang.org/x that
    has been around for as long as the encoding package, we should
    probably discuss it on golang-dev first, if not file a formal
    proposal.

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

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupgolang-nuts @
categoriesgo
postedDec 15, '15 at 9:42p
activeDec 18, '15 at 11:39p
posts5
users4
websitegolang.org

People

Translate

site design / logo © 2022 Grokbase