search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
123.28k stars 17.57k forks source link

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

Open mvdan opened 2 years ago

mvdan commented 2 years ago

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 commented 1 year ago

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.

seankhliao commented 3 months ago

presumably with the go directive in go.mod becoming the minimum required version, it's less relevant and you could just browse the docs for the lowest version you're targeting?