Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation around stamping #25122

Open
swarren12 opened this issue Jan 29, 2025 · 1 comment
Open

Improve documentation around stamping #25122

swarren12 opened this issue Jan 29, 2025 · 1 comment
Labels
help wanted Someone outside the Bazel team could own this P2 We'll consider working on this in future. (Assignee optional) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website type: documentation (cleanup)

Comments

@swarren12
Copy link

swarren12 commented Jan 29, 2025

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:

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 #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".

@swarren12 swarren12 added team-Documentation Documentation improvements that cannot be directly linked to other team labels type: documentation (cleanup) untriaged labels Jan 29, 2025
@fmeum
Copy link
Collaborator

fmeum commented Jan 29, 2025

https://github.com/bazel-contrib/bazel-lib/blob/main/docs/stamping.md provides a useful wrapper around what Bazel exposes.

@iancha1992 iancha1992 added the team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website label Jan 29, 2025
@meteorcloudy meteorcloudy added P2 We'll consider working on this in future. (Assignee optional) help wanted Someone outside the Bazel team could own this and removed untriaged labels Feb 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Someone outside the Bazel team could own this P2 We'll consider working on this in future. (Assignee optional) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website type: documentation (cleanup)
Projects
None yet
Development

No branches or pull requests

6 participants