Revise codelab for Go module management with Puku #3437
+414
−335
Conversation
This file contains hidden or 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
Updated the codelab to reflect changes in dependency management with Puku, including renaming and clarifying instructions for adding, updating, and removing Go third-party dependencies.
Birkalo
requested changes
Nov 11, 2025
Birkalo
left a comment
Birkalo
left a comment
There was a problem hiding this comment.
I'm not going to get to the rest of this today unfortunately, but there's some comments here
docs/codelabs/go_module.md
Outdated
| summary: Third-party dependencies with go_module() | ||
| description: Set up gRPC and learn how to manage third party dependencies with Please | ||
| summary: Third-party dependencies with Puku | ||
| description: Add, update, pin, and remove Go third-party dependencies using go get and plz puku (no go_module()) |
There was a problem hiding this comment.
Suggested change
| description: Add, update, pin, and remove Go third-party dependencies using go get and plz puku (no go_module()) | |
| description: Add, update, pin, and remove Go third-party dependencies using go get and plz puku |
docs/codelabs/go_module.md
Outdated
| description: Set up gRPC and learn how to manage third party dependencies with Please | ||
| summary: Third-party dependencies with Puku | ||
| description: Add, update, pin, and remove Go third-party dependencies using go get and plz puku (no go_module()) | ||
| id: go_module |
docs/codelabs/go_module.md
Outdated
| Now add the dependency with `go get`: | ||
|
|
||
| ```bash | ||
| GOTOOLCHAIN=local go get github.com/google/uuid |
There was a problem hiding this comment.
Do we need GOTOOLCHAIN=local at the start of this? I didn't during my test, and if they've set it up properly in the steps above it might not be necessary
docs/codelabs/go_module.md
Outdated
|
|
||
| ### Example scenario | ||
|
|
||
| Let's say a new version of `uuid` has a breaking change. Pin it to a working version: |
There was a problem hiding this comment.
Suggested change
| Let's say a new version of `uuid` has a breaking change. Pin it to a working version: | |
| Let's say a new version of `uuid` has introduced a breaking change. Pin it to a working version: |
nitpick
docs/codelabs/go_module.md
Outdated
Comment on lines
309
to
353
| ### Steps to remove a module | ||
|
|
||
| 1. **Verify no dependencies exist:** | ||
|
|
||
| ```bash | ||
| plz query revdeps //third_party/go:module_name --level=-1 | grep -v //third_party/go | ||
| ``` | ||
|
|
||
| If this returns no results, the module is safe to remove. | ||
|
|
||
| 2. **Remove the `go_repo()` target from `third_party/go/BUILD`:** | ||
|
|
||
| Open `third_party/go/BUILD` and delete the corresponding `go_repo()` rule. | ||
|
|
||
| 3. **Remove from `go.mod` and `go.sum`:** | ||
|
|
||
| ```bash | ||
| go mod edit -droprequire github.com/example/module | ||
| go mod tidy | ||
| ``` | ||
|
|
||
| 4. **Sync the changes:** | ||
|
|
||
| ```bash | ||
| plz puku sync -w | ||
| ``` | ||
|
|
||
| And update our `:grpc` rule to add `:genproto_rpc` as a dependency: | ||
| **Note:** Puku does not currently automate module removal, so this process is manual. | ||
|
|
||
| ### Example | ||
|
|
||
| Let's say we want to remove an unused module: | ||
|
|
||
| ```bash | ||
| # Check for dependencies | ||
| plz query revdeps //third_party/go:unused_module --level=-1 | grep -v //third_party/go | ||
|
|
||
| # If safe, remove from go.mod | ||
| go mod edit -droprequire github.com/unused/module | ||
| go mod tidy | ||
|
|
||
| # Manually delete the go_repo() rule from third_party/go/BUILD | ||
| # Then sync | ||
| plz puku sync -w | ||
| ``` |
There was a problem hiding this comment.
This section repeats itself, probably worth consolidating it
docs/codelabs/go_module.md
Outdated
| - Please installed and configured: https://please.build/quickstart.html | ||
| - Go 1.20+ installed and on PATH | ||
| - Puku available in one of the following ways: | ||
| - Via Please alias: add an alias to `.plzconfig` (see below), or |
There was a problem hiding this comment.
below
The steps aren't below, they're on the next page.
docs/codelabs/go_module.md
Outdated
| - Please installed and configured: https://please.build/quickstart.html | ||
| - Go 1.20+ installed and on PATH | ||
| - Puku available in one of the following ways: | ||
| - Via Please alias: add an alias to `.plzconfig` (see below), or |
There was a problem hiding this comment.
Suggested change
| - Via Please alias: add an alias to `.plzconfig` (see below), or | |
| - Via a Please alias (guide in next step) |
docs/codelabs/go_module.md
Outdated
Comment on lines
31
to
33
| - Installed locally (if the first doesn't work, try the second): | ||
| - `go install github.com/please-build/puku/cmd/puku@latest` | ||
| - `go get github.com/please-build/puku/cmd/puku` |
There was a problem hiding this comment.
Suggested change
| - Installed locally (if the first doesn't work, try the second): | |
| - `go install github.com/please-build/puku/cmd/puku@latest` | |
| - `go get github.com/please-build/puku/cmd/puku` | |
| - Installed locally with either: | |
| - `go install github.com/please-build/puku/cmd/puku@latest` | |
| or | |
| - `go get github.com/please-build/puku/cmd/puku` |
docs/codelabs/go_module.md
Outdated
Comment on lines
35
to
41
| ### What you’ll learn | ||
| - Add and upgrade dependencies with `go get` | ||
| - Sync `go.mod` into `third_party/go/BUILD` with `plz puku sync` | ||
| - Let `plz puku fmt` add third-party deps to your BUILD targets | ||
| - Diagnose missing imports and missing subrepos | ||
| - Pin or exclude dependency versions with `go mod edit` | ||
| - Remove third-party modules safely |
There was a problem hiding this comment.
Is this not the same as the ### Goals section above? I'd combine the two into a single section
docs/codelabs/go_module.md
Outdated
|
|
||
| ## Initialising your project | ||
| Duration: 2 | ||
| ## Initialising your project and running puku with please |
There was a problem hiding this comment.
Suggested change
| ## Initialising your project and running puku with please | |
| ## Initialising your project and running Puku with Please |
added 2 commits
November 12, 2025 06:36
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.
Updated the codelab to reflect changes in dependency management with Puku, including renaming and clarifying instructions for adding, updating, and removing Go third-party dependencies.