Document support/expectations for consuming ko as a library

[imjasonh]

From: https://www.reddit.com/r/golang/comments/rhyn52/should_i_import_code_from_open_source_projects/

Since the hard work by @halvards in #348, ko's build behavior is more easily consumable by other code that wants it. That's undeniably great. 👏

We could do a better job of documenting how to do that, either in README or in a separate page that's linked from README. Something simple like documenting how the build package works, and feeds into the publish package, with links to godoc to explore the full set of options.

We should also document expectations about stability of those packages. I'd like to make it clear that ko-the-CLI is the main way we expect people to consume the behavior, but that packages are available on a best-effort basis. There's CLI behavior we don't make available as a package (e.g., internal/sbom), and there might be changes to the packages to improve the CLI experience (e.g., #551) that may break consumers of the Go packages -- we'll try to limit the severity, but I don't think we should commit to full compatibility indefinitely. Upon upgrading a dependency on github.com/google/ko, consumers may have build breakages or behavior changes.

Thoughts? @halvards @jonjohnsonjr

[StevenACoffman]

From the peanut gallery, I would personally love it if you made a really simple example of using ko as a library showing how to publish an image with a tag while passing some ldflags. My use case has a little bit of friction with the current cli + config.

For my selfish use case, I wish to build my application and use the git SHA1 both as the image tag as well as inject the git SHA1 into the go binary at build time. Currently, I need to manipulate the KO_DOCKER_REPO, the .ko.yaml, and some other environment variables to make that happen, which requires some scripting, which I'd rather just do in Go than in shell scripts.

[imjasonh]

@StevenACoffman That's a useful request, far from a peanut gallery.

I think we could document something like this gist that's a pretty minimal ko-alike that builds and publishes images.

[StevenACoffman]

Thanks! That's so exactly what I wished for! Also perhaps noting that dvob/sko is this without the ldflags.

[halvards]

@imjasonh how about adding the contents of that gist to the repo? Say under examples/sdk?

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Keep fresh with the 'lifecycle/frozen' label.