gtristan commented on code in PR #1997:
URL: https://github.com/apache/buildstream/pull/1997#discussion_r2011780986
##########
src/buildstream/source.py:
##########
@@ -262,10 +262,123 @@ def __init__(
@dataclass
class AliasSubstitution:
+ """AliasSubstitution()
+ An opaque data structure which may be passed through
+ :func:`SourceFetcher.fetch() <buildstream.source.SourceFetcher.fetch>` and
in such cases
+ must be provided to :func:`Source.translate_url()
<buildstream.source.Source.translate_url>`.
+ """
+
_effective_alias: str
_mirror: Union[SourceMirror, str]
+class SourceInfoMedium(FastEnum):
+ """
+ Indicates the meduim in which the source is obtained
+
+ *Since: 2.5*
+ """
+
+ LOCAL = "local"
+ """
+ Files stored locally in the project
+ """
+
+ ARCHIVE = "archive"
+ """
+ An archive file
+ """
+
+ GIT = "git"
+ """
+ A git repository
+ """
+
+
+class SourceVersionType(FastEnum):
+ """
+ Indicates the type of the version string
+
+ *Since: 2.5*
+ """
+
+ VERSION = "version"
+ """
+ The upstream version string, which may be semantic version
+ """
+
+ COMMIT = "commit"
+ """
+ A commit string which accurately represents a version in a source
+ code repository or VCS
+ """
+
+ SHA256 = "sha256"
+ """
+ An sha256 checksum
+ """
+
+ DIGEST = "digest"
+ """
+ A CAS digest representing the unique version of this source input
+ """
+
+
+class SourceInfo:
+ """SourceInfo()
+
+ An object representing the provenance of input reported by
+ :func:`Source.collect_source_info()
<buildstream.source.Source.collect_source_info>`
+
+ *Since: 2.5*
+ """
+
+ def __init__(self, url: str, medium: str, version_type: str, version: str):
+ # XXX assert medium and version_type are valid values for the enums
+
+ self.url: str = url
+ """
+ The url of the source input
+ """
+
+ self.medium: str = medium
+ """
+ The :class:`.SourceInfoMedium` of the source input
+ """
+
+ self.version_type: str = version_type
Review Comment:
> In general, I feel that it's way easier to determine the version of a
tarball than it is to extract the version from a git tag. The tarball naming is
just more consistent.
On the face of it, this *appears* to be true.
Here is my thoughts about trust, though - with a git repo, I have a higher
level of *trust* that a given release tag means that the content I am getting
*is that actual release*.
With a tarball on the other hand, I get an sha256sum and I get a filename.
That filename has numbers in it.
Yes it's true that by convention, for a staggering majority of tarballs out
there in the wild, the number in the filename is somehow related to the
*version* of software you'll get in the tarball, for a CLI tool you might see
that number when you type `cli --version`.
In order to *produce version information* that is reliable, I'm not sure it
can be completely automated, perhaps at least a human being, when adding the
`.bst` files to a project or when updating those, needs to at least sign off on
the *way that we extract the version*.
What I'm getting at, is that overall, I'm not comfortable with any statement
like:
> *"This plugin knows how to get the version of this upstream data blob"*
We just don't *really* know what the version is at any time, not without at
least looking at the upstream project, reading about its release policy and
figuring it out.
--
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: commits-unsubscr...@buildstream.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
