Since #375 we have an optional go.work file local developers may generate with the Makefile. The purpose of this go.work file is to make sure that examples can locally use code that's not released in an official package tag yet. We do not commit it, however, since it's generally a bad idea to commit go.work files in package repos (see https://github.com/golang/go/issues/53502#issuecomment-1939705751) about the latest guideline from the Go team).
However, this still creates issues: most visibly, examples have to be bound to released versions of the package in-tree, because otherwise CI fails (CI doesn't have a go.work file available). Some recent examples:
783 updates examples to new APIs that were changed on main, but this PR cannot land until the next tag is made because it will fail in CI
777 adds new functionality and an example for it, but the example cannot land in the same PR because building it will fail - the new functionality isn't in a tagged release yet
There are several solutions we can implement:
Allow replace lines in the go.mod files of examples. This will mean that examples will always use the in-tree version of the package, and examples can be updated before new tags are made. This will also mean that users look at examples and try them but it sometimes won't work with released versions of the package, unless the user checks out the entire repo.
Place go.work files in each examples/<dir> - this is equivalent to (1), and is OK per guidelines since we don't expect anyone ever importing our examples. Same disadvantages as (1)
Leave things as they are, but be aware that examples need follow-up PRs and new tags. In essence, whenever the langchaingo public API changes or is augmented (with new features, modules, etc), a new tag has to be made so examples can be updated and build properly in CI. Tags are cheap (= free) and relatively safe in Go because they don't force upgrade in client code (go get -u has to be done explicitly), but this is something we'll need to remember to do much more often. There's some prior art to this - for example the https://github.com/googleapis/google-cloud-go repository has a bot that automatically tags new releases after every "feature" PR that lands.
Since #375 we have an optional
go.workfile local developers may generate with theMakefile. The purpose of thisgo.workfile is to make sure that examples can locally use code that's not released in an official package tag yet. We do not commit it, however, since it's generally a bad idea to commitgo.workfiles in package repos (see https://github.com/golang/go/issues/53502#issuecomment-1939705751) about the latest guideline from the Go team).However, this still creates issues: most visibly, examples have to be bound to released versions of the package in-tree, because otherwise CI fails (CI doesn't have a
go.workfile available). Some recent examples:783 updates examples to new APIs that were changed on
main, but this PR cannot land until the next tag is made because it will fail in CI777 adds new functionality and an example for it, but the example cannot land in the same PR because building it will fail - the new functionality isn't in a tagged release yet
There are several solutions we can implement:
replacelines in thego.modfiles of examples. This will mean that examples will always use the in-tree version of the package, and examples can be updated before new tags are made. This will also mean that users look at examples and try them but it sometimes won't work with released versions of the package, unless the user checks out the entire repo.go.workfiles in eachexamples/<dir>- this is equivalent to (1), and is OK per guidelines since we don't expect anyone ever importing our examples. Same disadvantages as (1)go get -uhas to be done explicitly), but this is something we'll need to remember to do much more often. There's some prior art to this - for example the https://github.com/googleapis/google-cloud-go repository has a bot that automatically tags new releases after every "feature" PR that lands.