Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: "added in version" does not account for new packages #51013

Open
mvdan opened this issue Feb 4, 2022 · 1 comment
Open

x/pkgsite: "added in version" does not account for new packages #51013

mvdan opened this issue Feb 4, 2022 · 1 comment
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite

Comments

@mvdan
Copy link
Member

mvdan commented Feb 4, 2022

The "added in vX" notes on the rendered API pages are super useful, and they work for both the Go project itself, as well as any module with releases, e.g:

However, there's no such "added in" information when a package started existing at a specific version. Two examples:

I think that information should be surfaced, because otherwise a user could easily fall into the trap that is assuming that, for example, https://pkg.go.dev/github.com/ipld/go-ipld-prime/node/bindnode#Prototype is safe to use on any version - since it has no "added in" information attached.

One solution would be to add "added in" information to the top of the package view, to inform at what version the package was added. This could be something as simple as "the first stable release the package was seen in this module", becauses I imagine and hope that adding a package, removing it, and adding it again should be extremely rare. I also imagine that the logic should be consistent with whatever algorithm the current API-based "added in" notes are computed with.

Another solution could be to add "added in" to all the APIs that were added with the package in the first place. This will be more visually consistent with what we've got now, and perhaps less prone to footguns, as a link to https://pkg.go.dev/github.com/ipld/go-ipld-prime/node/bindnode#Prototype will quickly give me that important information without me having to scroll all the way up and notice it.

I think the best solution is to do both; adding the information to each API is consistent and very clear, and adding it at the top is also relevant, because a package could have 0 exported API or have its own effect even if we don't use any of its API, via init functions.

cc @golang/pkgsite

@mvdan mvdan added the pkgsite label Feb 4, 2022
@gopherbot gopherbot added this to the pkgsite/unplanned milestone Feb 4, 2022
@jba jba added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. FeatureRequest labels Feb 7, 2022
@mvdan
Copy link
Member Author

mvdan commented Sep 7, 2023

I wanted to gently nudge this issue - with std gaining many new packages like slices, maps, or log/slog, it is surprisingly difficult to figure out whether I can use them, since pkgsite tells me nothing about what Go version introduced them or their initial APIs.

So far, the best workaround I've found is to manually go to my Go checkout and grep the api/ directory.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Development

No branches or pull requests

3 participants