Improve documentation for --publish flag

[mgreen-sm]

Description

As a new user to Buildpacks, I found the documentation / help on the build --publish flag to be sparse. As a result, I was not fully aware of its function ("how to use it" and "what is it for"). The documentation / help merely states: "Publish to registry".

This confused me, because the documentation / help also speaks of registry for multiple other options (config registry-mirror, config registries and also provides limited information about the --publish flag for other options (builder create --publish, buildpack package --publish).

Aside from being accustomed to push instead of publish (Docker), I had related the build --publish with the other options (resorting to an extra docker push .... step in the pipeline).

Only in the documentation itself, in the "App Developer Guide: Cache Images" section specifically, was it made clear that the build --publish would push the image the registry specified as part of the image name, and that it had no relation to other options (or would be published publicly somewhere not intended).

Proposed solution

Use similar wording as in the Docker documentation to clarify the purpose of build --publish:

Use (--publish) to share your images to the Docker Hub registry or to a self-hosted one.

Refer to the image tag reference for more information about valid image and tag names.

This should answer both the "what is it for" and "how to use it".

The last line in the example above ("Refer to ...") may also apply to the --cache-image option, so could be consolidated in the help / documentation as with Docker's documentation.

Additionally, expand the "App Developer Guide" to include an example similar to the "Cache Images" section.

Additional context

• Stack Overflow - Question posted by another user about pack build --publish due to sparsity

[h4l0gen]

hey @mgreen-sm , i would like to work on this issue . could you please help me out to work on this , Thanks

[cmoulliard]

Documentation should also better explain how to set the credentials to publish the image created within the registry: quay.io, docker.io etc and how to get a more verbose message instead of

export CNB_REGISTRY_AUTH=/Users/cmoullia/.docker/config.json
pack builder create -v quay.io/swowdrop/ubi-builder --config ubi-builder.toml --publish
...
Adding extension paketo-community/[email protected] (diffID=sha256:71b958166ca5b4fdec5734dd34a3175bef471f91a4c50d9664b43f4014ea6a56)
ERROR: failed to write image to the following tags: [quay.io/swowdrop/ubi-builder: HEAD https://quay.io/v2/swowdrop/ubi-builder/manifests/latest: unexpected status code 401 Unauthorized (HEAD responses have no body, use GET for details)]

[rizul2108]

I want to work on this issue. Can any maintainer please assign this issue to me ?
@natalieparellano

[rizul2108]

Additionally, expand the "App Developer Guide" to include an example similar to the "Cache Images" section.

does this mean I have to add an example demonstrating how to use publish flag to push to a registry?