FAQ
While contributing to fsnotify, it has become necessary to make some API
changes.

Though it isn't officially v1.0.0+ stable, we'd like to avoid breaking the
55 packages that import it. Rather than changing methods, new ones are
added. Old constants are kept around.

I've added comments in the form "// DEPRECATED(-): please use Path()
instead" which godoc apparently treats as Notes?

However, the API docs are starting to get cluttered, to the point that they
would be confusing for a newcomer to the library.

I tried running godoc with -notes="DEPRECATED", but that just adds a
section called "Deprecateds" (sic) to the end.

So I'm wondering if there is a way to hide exported identifiers? Perhaps
not permanently hide, but maybe folding them away, or grouping them at the
end?

How would this look to the end-user? And what comments would the library
maintainer need to add?

I'm sure the Go Authors are pretty occupied getting Go 1.2 out the door,
but I thought it was worth starting the conversation.

Thanks, Nathan.


--
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/groups/opt_out.

Search Discussions

  • Aram Hăvărneanu at Sep 22, 2013 at 4:07 pm
    Just ship a custom gofix that updates people's code to the new API.
    Gofix is too great not to be used.

    --
    Aram Hăvărneanu

    --
    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/groups/opt_out.
  • Jan Mercl at Sep 22, 2013 at 4:14 pm
    On Sun, Sep 22, 2013 at 6:04 PM, Nathan Youngman wrote:

    AFAICS, the fsnotify package has [0] in it's parent directory, ie.
    it's explicitly expected to break it's API, which is the reason why it
    is in the exp subrepositrory in the first place.

       [0]: https://code.google.com/p/go/source/browse/README?repo=exp

    -j

    --
    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/groups/opt_out.
  • Nathan Youngman at Sep 22, 2013 at 6:13 pm
    Aram:

    Even writing a custom gofix module (easier said than done) still requires a
    deprecation window.

    Consider someone installing Revel who finds that it doesn't even compile
    because fsnotify changed its API. Until robfig has a chance to apply/test
    the gofix, it would be broken. Expecting the users of Revel to gofix or
    make due it is a non-starter. Yes, there are solutions via revision
    locking, dependency management, yada, yada. None of that is relevant to
    this RFC, so lets not go there.

    Deprecating functionality rather than removing it outright is the *courteous
    * thing to do.

    Jan:

    While it's true that go.exp and semantic versions < v1.0.0 allow breaking
    changes, that doesn't mean we should if we can find another way. Again, 55
    packages import fsnotify according to godoc.org.

    My solution for now will be to improve the usage section of the README, but
    a way to improve the godoc library/cmd/.org remains an open question.

    Nathan.


    --
    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/groups/opt_out.
  • Jan Mercl at Sep 22, 2013 at 6:39 pm

    On Sun, Sep 22, 2013 at 8:13 PM, Nathan Youngman wrote:
    While it's true that go.exp and semantic versions < v1.0.0
    I don't think the go.exp sub repository has any semantic version above
    that it is included in release point Go 1.1.2.
    allow breaking
    changes, that doesn't mean we should if we can find another way.
    Then the 'experimental' status is not effectively void.

    IMHO, it's just the opposite. The experimental status allows to find
    the best possible API, also by experiences from the current
    (experimental) API design. If backwards compatibility is a concern
    then that clearly contradicts such goal.
    Again, 55
    packages import fsnotify according to godoc.org.
    If the number should perhaps imply that the experimental status no
    more applies then I must have misunderstood the previously linked
    README:

    """"
    Warning: Packages here are experimental and unreliable. Some may
    one day be promoted to the main repository or other subrepository,
    or they may be modified arbitrarily or even disappear altogether.

    In short, code in this subrepository is not subject to the Go 1
    compatibility promise. (No subrepo is, but the promise is even more
    likely to be violated by go.exp than the others.)
    """"

    It's perhaps also worth a note, that changes to the go.exp
    subrepository can actually break nothing. The code is always compiler
    aginst the locally installed version of any package. Unless a
    developer intentionally and explicitly (go get -u or foo pull) updates
    that local copy, nothing happens to it.

    -j

    --
    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/groups/opt_out.
  • Nathan Youngman at Sep 23, 2013 at 4:38 pm
    "The experimental status allows to find
    the best possible API. If backwards compatibility is a concern then that clearly contradicts such goal."

    Very good point. I'll think on that more, and possibly write about it alongside the merits of deprecations.

    To clear up the present situation, I'm am talking about the import path at: https://github.com/howeyc/fsnotify

    The go.exp mirror has far less dependents.

    Whether or not for the present situation, I still think the handling of deprecations in Go is a good conversation to have.

    Nathan.

    --
    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/groups/opt_out.
  • Minux at Sep 23, 2013 at 4:50 pm

    On Mon, Sep 23, 2013 at 11:37 AM, Nathan Youngman wrote:

    Whether or not for the present situation, I still think the handling of
    deprecations in Go is a good conversation to have.
    Let's think about the usage scenarios.

    first, we have to agree that we can't let compiler to point out the usage
    of deprecated API in programs/packages.
    (Go compiler doesn't support warning, and give an error for that clearly
    doesn't fit; besides, Go frowns upon source
    code annotations)

    one package uses a deprecated API, will the author of that package
    frequently check the status of that API?
    I think not because it's not enforced (gcc has deprecated API warning, but
    Go doesn't have, this is the main
    problem, relying on authors to check for that is unrealistic).
    I suspect the only time when he/she notices the API change is when the
    deprecated API is removed and build
    breaks.

    For this scenario, I think it's in fact better to just break the build and
    release gofix modules for authors
    to easily update their packages (esp. for packages already declared to be
    experimental).

    Then let's consider potential users of the package, if API is deprecated,
    why not just remove the API so that
    user won't even consider it at the first place?

    I think more acceptable way of handling that is either:
    1. commit to a stable API (like Go stdlib), and only make backward
    compatible change.
    2. if really needed, break sooner than later, as it will be broken in the
    end anyway; break sooner means hitting
    less packages.

    --
    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/groups/opt_out.
  • Martin Angers at Sep 23, 2013 at 6:27 pm
    Just throwin' my 2 cents, I have no strong opinion either way, but there's
    also the Gustavo's V1/V2 way (see mgo). At least for the github repo (the
    exp could break without warning, as Jan pointed out, that's the point of
    exp, and exp/html did it a while ago when it was in exp). V1 would be the
    current path, obviously, and a new V2 path would be created.

    Le lundi 23 septembre 2013 12:49:35 UTC-4, minux a écrit :

    On Mon, Sep 23, 2013 at 11:37 AM, Nathan Youngman <junk...@nathany.com<javascript:>
    wrote:
    Whether or not for the present situation, I still think the handling of
    deprecations in Go is a good conversation to have.
    Let's think about the usage scenarios.

    first, we have to agree that we can't let compiler to point out the usage
    of deprecated API in programs/packages.
    (Go compiler doesn't support warning, and give an error for that clearly
    doesn't fit; besides, Go frowns upon source
    code annotations)

    one package uses a deprecated API, will the author of that package
    frequently check the status of that API?
    I think not because it's not enforced (gcc has deprecated API warning, but
    Go doesn't have, this is the main
    problem, relying on authors to check for that is unrealistic).
    I suspect the only time when he/she notices the API change is when the
    deprecated API is removed and build
    breaks.

    For this scenario, I think it's in fact better to just break the build and
    release gofix modules for authors
    to easily update their packages (esp. for packages already declared to be
    experimental).

    Then let's consider potential users of the package, if API is deprecated,
    why not just remove the API so that
    user won't even consider it at the first place?

    I think more acceptable way of handling that is either:
    1. commit to a stable API (like Go stdlib), and only make backward
    compatible change.
    2. if really needed, break sooner than later, as it will be broken in the
    end anyway; break sooner means hitting
    less packages.
    --
    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/groups/opt_out.
  • Nathan Youngman at Sep 24, 2013 at 1:07 am

    On Monday, 23 September 2013 10:49:35 UTC-6, minux wrote:
    Let's think about the usage scenarios.

    first, we have to agree that we can't let compiler to point out the usage
    of deprecated API in programs/packages.
    (Go compiler doesn't support warning, and give an error for that clearly
    doesn't fit; besides, Go frowns upon source
    code annotations)
    Yes, warnings would be in the territory of go vet or a similar tool.

    Presumably the annotations would be in a comment, such as the Note form
    currently used for BUG, etc.
      http://godoc.org/go/doc#Note

    one package uses a deprecated API, will the author of that package
    frequently check the status of that API?
    I think not because it's not enforced (gcc has deprecated API warning, but
    Go doesn't have, this is the main
    problem, relying on authors to check for that is unrealistic).
    I suspect the only time when he/she notices the API change is when the
    deprecated API is removed and build
    breaks.
    There are plenty of ways to bring this to the attention of developer in
    addition to go vet. Especially if the developer *wants* to be aware of
    deprecations. Anything from Changelogs to dashboards to code analysis
    badges turning yellow. In addition, if the dependent library/project is
    open source, others could send a pull request/patch.

    It's not as blatantly obvious as gcc's compile-time warnings, but that
    doesn't mean we should give up so easily.

    For this scenario, I think it's in fact better to just break the build and
    release gofix modules for authors
    to easily update their packages (esp. for packages already declared to be
    experimental).
    I would prefer to deprecate functionality until the next major version,
    which will clean up past deprecations. If gives people *time* to adapt. And
    a gofix module could still be useful at this time.

    It's plausible to gather information on (open source) dependents using the
    deprecated APIs to help determine when it's a good time to push out the
    next major release.

    That said, I'm a fan of Kyle Lemons idea to inject deprecation notes at the
    call site using gofix, in particular if gofix is unable to rewrite the code
    automatically or if doing so would change some underlying behavior as well.

    Then let's consider potential users of the package, if API is deprecated,
    why not just remove the API so that
    user won't even consider it at the first place?
    That was my original reason for this thread, hiding the deprecated
    identifiers from documentation.

    I also asked DisposaBoy about excluding them from code completion, though I
    have yet to talk to the developer of gocode itself.

    I think more acceptable way of handling that is either:
    1. commit to a stable API (like Go stdlib), and only make backward
    compatible change.
    2. if really needed, break sooner than later, as it will be broken in the
    end anyway; break sooner means hitting
    less packages.
    I think the main issue with a methodology that uses deprecations is what
    Jan already mentioned. It could make it harder to come up with the best API
    if too much attention is spent on maintaining compatibility. Everything
    else I've heard can be solved.



    --
    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/groups/opt_out.
  • Eric Gavaletz at Sep 24, 2013 at 9:32 pm
    I ran into a problem where godoc does not support the "tags" arg that go
    build supports for passing build tags (related thread<https://groups.google.com/d/topic/golang-nuts/Ntjs1zpAM-g/discussion>).
      IF godoc did support tags (as of now it does not), then could you move
    deprecated code to its own file and add a // +build deprecated tag to the
    file. Then developers would need to make a conscious choice to use the old
    stuff, but it is still there if they need it. The same *could* be said
    with godoc when/if it ever supports the "tags" arg.
    On Sunday, September 22, 2013 12:04:32 PM UTC-4, Nathan Youngman wrote:

    While contributing to fsnotify, it has become necessary to make some API
    changes.

    Though it isn't officially v1.0.0+ stable, we'd like to avoid breaking the
    55 packages that import it. Rather than changing methods, new ones are
    added. Old constants are kept around.

    I've added comments in the form "// DEPRECATED(-): please use Path()
    instead" which godoc apparently treats as Notes?

    However, the API docs are starting to get cluttered, to the point that
    they would be confusing for a newcomer to the library.

    I tried running godoc with -notes="DEPRECATED", but that just adds a
    section called "Deprecateds" (sic) to the end.

    So I'm wondering if there is a way to hide exported identifiers? Perhaps
    not permanently hide, but maybe folding them away, or grouping them at the
    end?

    How would this look to the end-user? And what comments would the library
    maintainer need to add?

    I'm sure the Go Authors are pretty occupied getting Go 1.2 out the door,
    but I thought it was worth starting the conversation.

    Thanks, Nathan.

    --
    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/groups/opt_out.
  • Nathan Youngman at Sep 24, 2013 at 11:23 pm
    Eric,

    I like that approach.

    It probably won't work for 100% of deprecations, such as one field in a larger struct. Those would still need to be marked with a comment, and left in the docs, but it's still an improvement.

    I like how this wouldn't require something specific for deprecations, but instead rely on a more general solution around build tags.

    It also makes it easy to remove support for deprecated APIs later: `rm deprecated.go`.

    Nathan

    --
    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/groups/opt_out.
  • Eric Gavaletz at Sep 25, 2013 at 2:35 am
    I am going to try to find time to look into coming up with a patch for
    this, but here is an open issue on the matter.

    https://code.google.com/p/go/issues/detail?id=3398


    On Tuesday, September 24, 2013 7:23:10 PM UTC-4, Nathan Youngman wrote:


    Eric,

    I like that approach.

    It probably won't work for 100% of deprecations, such as one field in a
    larger struct. Those would still need to be marked with a comment, and left
    in the docs, but it's still an improvement.

    I like how this wouldn't require something specific for deprecations, but
    instead rely on a more general solution around build tags.

    It also makes it easy to remove support for deprecated APIs later: `rm
    deprecated.go`.

    Nathan
    --
    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/groups/opt_out.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupgolang-nuts @
categoriesgo
postedSep 22, '13 at 4:04p
activeSep 25, '13 at 2:35a
posts12
users6
websitegolang.org

People

Translate

site design / logo © 2022 Grokbase