gtristan commented on issue #1685: URL: https://github.com/apache/buildstream/issues/1685#issuecomment-1196346500
> Related to this, we should also have a recommendation for how plugins should store their ref (and consequently what type should `Source.get_ref()` return). For plugins where ref is a scalar it's pretty obvious, but when it's a sequence or even more complex it's way less obvious how to navigate between `load_ref()`, `get_ref()` and `set_ref()` and keep them all happy. > > I find this very confusing, and whoever wrote the `cargo` plugin too. And even though I tried to fix it by porting changes from bst-external. I still find that it's not correct. Maybe it's worth documenting that the plugin restrict it's ref value to occupying only a single *key* in the node passed to `Source.set_ref()`, and that *that key's value* is what is expected to be returned by `Source.get_ref()` is the value for *that key* (which is typically named *"ref"* by the plugin). The actual type of the *value* of the ref is only expected to be a simple python data structure, using only `dict`, `list` and normal scalar values such as `str` and `int`. Python *typing* syntax does not allow us to strongly specify this constraint on our `SourceRef` definition (I believe the possibly recursive nature of the type definition is what prevents this), but we should ensure this is documented. While the actual value structure of the ref is irrelevant to buildstream, it should also be noted that the *order of elements* in a `list` and the *order of keys* in a `dict` is relevant and that the plugin should use stable algorithms to generate these, otherwise the plugin risks generating random cache keys. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
