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.

Sign up for GitHub

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

Jump to bottom

x/pkgsite: examples should run using the same version as the docs #50769

Closed
rogpeppe opened this issue Jan 24, 2022 · 6 comments
Closed

x/pkgsite: examples should run using the same version as the docs #50769

rogpeppe opened this issue Jan 24, 2022 · 6 comments
Assignees
@dle8
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Milestone
pkgsite/unplanned

Comments

@rogpeppe
Copy link
Contributor

rogpeppe commented Jan 24, 2022 •
edited

When running an example within a package, I just noticed that the example does not run using the version that's being shown in the doc page.

Here's a screenshot that demonstrates the issue. The example, which compiles fine, fails to run because it uses a feature of the API that's not in the "latest" tag (v0.0.9). ISTM that the playground code within a particular version should be pinned to exactly that version (v0.0.10-0.20220124095424-0da3c8f5f56c in this case). I saw this issue here: https://pkg.go.dev/github.com/rogpeppe/retry@v0.0.10-0.20220124095424-0da3c8f5f56c.

image
@gopherbot gopherbot added this to the pkgsite/unplanned milestone Jan 24, 2022
@seankhliao
Copy link
Member

dup of #46689 ?

@rogpeppe
Copy link
Contributor Author

@seankhliao Thanks for bringing that issue up - I wasn't aware of it. Although it does seem to be the same underlying problem, I'd say that issue wasn't framed correctly. Pre-release version or not, I believe that any example should run in the context of the version that is being documented. Using the latest version is not appropriate for any version that isn't the latest version, and that applies doubly so when the major version is zero and backward compatibility is not guaranteed.

@jamalc jamalc added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 31, 2022
@jamalc
Copy link

jamalc commented Jan 31, 2022

The playground supports specifying module versions with an inline mod file. See this example. Maybe for documentation pages we could place an inline mod file into each example.

@rogpeppe
Copy link
Contributor Author

rogpeppe commented Feb 1, 2022

@jamalc Yes, that's exactly the kind of thing I was thinking of.

@jamalc jamalc mentioned this issue Apr 1, 2022
Closed
@dle8 dle8 self-assigned this Oct 14, 2022
@gopherbot
Copy link

Change https://go.dev/cl/444455 mentions this issue: static: add module versions with an inline mod file to run package examples

gopherbot pushed a commit to golang/pkgsite that referenced this issue Oct 25, 2022
static: add module versions with an inline mod file to run package ex…
834d746 
…amples

For all non-standard library packages, their examples in the docs are ran using the version as the docs by adding an inline mod file that specifies the module version of the package.

For golang/go#50769

Change-Id: I539260147aedade112a2e812c5ea4d19235774c2
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/444455
Reviewed-by: Jamal Carvalho <jamal@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Run-TryBot: Dylan Le <dungtuanle@google.com>
@dle8
Copy link

dle8 commented Oct 25, 2022

The problem is resolved in https://go.dev/cl/444455. Thanks @jamalc for the help!

@dle8 dle8 closed this as completed Oct 25, 2022
@ZekeLu ZekeLu mentioned this issue Oct 27, 2022
Open
@golang golang locked and limited conversation to collaborators Oct 25, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@dle8 dle8

Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
Projects
None yet
Milestone
pkgsite/unplanned
Development

No branches or pull requests
5 participants
@rogpeppe @gopherbot @seankhliao @jamalc @dle8