Improve documentation around stamping

Page link:

https://bazel.build/docs/user-manual

Problem description (include actual vs expected text, if applicable):

To be honest, I'm not sure what the best "page link" for this issue is, but user-manual seemed to have the most information already, so it seemed like an appropriate choice.

Stamping in Bazel is (imho) not very well documented. The details on the user-manual page describe how to use --workspace_status_command to generate the stable-status.txt and volatile-status.txt files, but they do not provide any information on how to use these files (or, why maybe we shouldn't be trying to).

Aspect Build does have some information over at stamping.md but since this is a feature built into Bazel, it doesn't feel like it's an appropriate place.

Some examples of what I would find useful to know:

• make ctx.info_file and ctx.version_file explicit in the documentation
  • they are documented at https://bazel.build/rules/lib/builtins/ctx, but this relies on knowing what to look for
• how to access the stable/volatile keys in custom rules
  • I found https://github.com/bazelbuild/bazel/issues/6786 which suggests that this isn't possible, but the documentation should be clear about this
  • Even in that issue, there's a comment that "We could allow implementing actions in Starlark, but they'd still be executed in the execution phase, not the analysis phase.", which suggests maybe it could be possible now?

From everything I've read, my current impression of the state of things is as follows:

• The stable-status.txt and volatile-status.txt files can be found via ctx in Starlark rules
• The stamped variables are not directly accessible in BUILD files or Starlark rules
• It is not possible to perform macro substitutions on these values
• When invoking an external executable, e.g. via ctx.actions.run(), is is only possible to pass the status file filenames, not their content

If the above are correct (and also the intended, long-term) behaviours, it would be useful to have an explanation of why in the documentation along with an example of what to do instead. For example, consider the following basic rule:

def _helm_package(ctx):
    helm_toolchain = ctx.toolchains["@helm//:toolchain_type"]

    app_version = "0"
    version = "develop"

    out_file_name = "%s.tgz" % ctx.attr.chart_name
    out_file = ctx.actions.declare_file(out_file_name)

    ctx.actions.run(
        mnemonic = "HelmPackage",
        executable = helm_toolchain.helm.exec,
        outputs = [out_file],
        inputs = ctx.files.srcs,
        arguments = [
            "package",
            "%s/%s" % (ctx.label.package, ctx.attr.chart_path_prefix),
            "--app-version", app_version,
            "--version", version,
            "--destination", out_file.dirname,
        ],
    )

    return [
        HelmPackage(chart = out_file),
        OutputGroupInfo(_validation = depset([lint_file, tap_file])),
    ]

When stamping is enabled, it would be useful to provide the stamped app_version and version to the ctx.actions.run() command, but currently I do not see any possible way to do this and (crucially imho) no explanation of why I shouldn't be able to.

The "obvious" workaround here would be to define a custom helm.sh wrapper script that takes the stable-status.txt and volatile-status.txt files, extracts the relevant keys, and then delegates to the underlying helm executable. This feels clunky; it feels like the kind of thing Bazel should just be able to do out-of-the-box, but without the documentation to support this, it's very hard to say either way.

Where do you see this issue? (include link to specific section of the page, if applicable)

I think, ideally, there should probably be an entire section on the user manual dedicated to stamping?

Right now, the most complete information seems to be found at:

https://bazel.build/docs/user-manual#workspace-status

Any other information you'd like to share?

I think (possibly) there's a feature request hidden inside here to resurrect https://github.com/bazelbuild/bazel/issues/6786, but current I am less interested in changing behaviour over just knowing definitively how it's meant to work and what the expectations are. Maybe my entire understanding of the purpose of stamping is flawed here and I'm trying to do something that I really shouldn't be (and that's fine, as long as it's clear why and what the "correct" approach should be).

It's also possible that what I'm after is already documented ... but I couldn't find it by searching for: "stamp", "stamping", "workspace_status_command" or "stable-status.txt".