Use project Go version for generating website content #353
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The "Deploy Website" (Cobra, versioned, MkDocs, Poetry) template is used to generate and publish a documentation website
for projects based on the Cobra command line application framework.
Command line reference pages are generated from the project's Go codebase.
Previously, the default version of Go from the GitHub Actions runner machine was used for generating the documentation
content. A recent update of this default Go version from 1.17 to 1.20 caused the generation process to fail during the
workflow runs in some projects that use older Go versions:
```
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0x83c1a6]
goroutine 1 [running]:
debug/elf.(*Section).ReadAt(0xc0001be000?, {0xc0001ce000?, 0x24?, 0x23?}, 0x23?)
<autogenerated>:1 +0x26
archive/zip.readDirectoryEnd({0xa37480, 0xc0000af580}, 0x210)
/opt/hostedtoolcache/go/1.20.3/x64/src/archive/zip/reader.go:581 +0xf5
archive/zip.(*Reader).init(0xc000137500, {0xa37480?, 0xc0000af580}, 0x210)
/opt/hostedtoolcache/go/1.20.3/x64/src/archive/zip/reader.go:124 +0x5c
archive/zip.NewReader({0xa37480, 0xc0000af580}, 0x210)
/opt/hostedtoolcache/go/1.20.3/x64/src/archive/zip/reader.go:103 +0x5e
github.com/daaku/go%2ezipexe.zipExeReaderElf({0xa38040?, 0xc0000140f0}, 0xdc51bf)
/home/runner/go/pkg/mod/github.com/daaku/[email protected]/zipexe.go:128 +0x8b
github.com/daaku/go%2ezipexe.NewReader({0xa38040, 0xc0000140f0}, 0x0?)
/home/runner/go/pkg/mod/github.com/daaku/[email protected]/zipexe.go:48 +0x98
github.com/daaku/go%2ezipexe.OpenCloser({0xc0000822a0?, 0xc0000e5720?})
/home/runner/go/pkg/mod/github.com/daaku/[email protected]/zipexe.go:30 +0x57
github.com/cmaglie/go%2erice.init.0()
/home/runner/go/pkg/mod/github.com/cmaglie/[email protected]/appended.go:42 +0x65
task: Failed to run task "go:cli-docs": exit status 2
```
This error, and the general fragility that comes from not controlling the Go version, is avoided by configuring the
workflow to use the specific version of Go that is used for development and validation of the project.
per1234
added
type: imperfection
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The "Deploy Website" (Cobra, versioned, MkDocs, Poetry) template is used to generate and publish a documentation website for projects based on the Cobra command line application framework.
Command line reference pages are generated from the project's Go codebase.
Previously, the default version of Go from the GitHub Actions runner machine was used for generating the documentation content. A recent update of this default Go version from 1.17 to 1.20 (actions/runner-images#7276) caused the generation process to fail during the workflow runs in some projects that use older Go versions:
This error, and the general fragility that comes from not controlling the Go version, is avoided by configuring the workflow to use the specific version of Go that is used for development and validation of the project.
This fix has already been applied to the installations of the template in several projects:
NOTE: I did not apply the equivalent patch to the "Check Markdown (task)" template as was done in arduino/arduino-lint#542 and arduino/arduino-fwuploader#167 because that template is intended to be applicable to any project, while the patch is only necessary in projects that use Go to generate Markdown-based documentation content. So the work needed on that template is not so straightforward as it is for the "Deploy Website" (Cobra, versioned, MkDocs, Poetry) template, which will always use Go in any project it is applied to.
I hope to find time to also follow up on improving the "Check Markdown (task)" template in this respect, but thought it best to at least immediately pull the straightforward fix up from the downstream projects.