Improve documentation around stamping #25122
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)
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 thestable-status.txt
andvolatile-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:
ctx.info_file
andctx.version_file
explicit in the documentationFrom everything I've read, my current impression of the state of things is as follows:
stable-status.txt
andvolatile-status.txt
files can be found viactx
in Starlark rulesctx.actions.run()
, is is only possible to pass the status file filenames, not their contentIf 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:
When stamping is enabled, it would be useful to provide the stamped
app_version
andversion
to thectx.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 thestable-status.txt
andvolatile-status.txt
files, extracts the relevant keys, and then delegates to the underlyinghelm
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".
The text was updated successfully, but these errors were encountered: