Repository navigation
fix(scripts): only a tag push may report a released version - #5564
Conversation
There was a problem hiding this comment.
I have already done a preliminary review for you, and I hope to help you do a better job.
Summary
This PR fixes an issue where branch pushes at released tags incorrectly report the tag as a released version. The solution introduces a --git_ref argument to differentiate between tag pushes and other build triggers, ensuring only tag pushes report a released version while others are handled as candidates. The implementation integrates seamlessly with existing logic, updates the relevant test cases, and includes documentation updates. Overall, the changes are well-structured and address the problem effectively.
Critical Issues
None identified.
Code Improvements
-
Function Name Clarity:
-
File:
scripts/flow/build/versioning-strategy.ts, lines 72-75 -
Issue: The function
candidateVersionis clear in its intent but could benefit from a more precise name indicating that it adjusts versions for non-tag builds. -
Suggestion: Consider renaming
candidateVersionto something likeadjustForNonTagBuildsfor better clarity.function adjustForNonTagBuilds(rv: semver.SemVer): builtControl { return { releaseVersion: `v${rv.major}.${rv.minor}.${rv.patch + 1}-pre`, }; }
-
-
Default Value Handling for
gitRef:-
File:
scripts/flow/build/versioning-strategy.ts, line 84 -
Issue: The default value
""forgitRefis overly permissive. A missing or invalidgitRefshould ideally trigger an explicit error or warning, as it could indicate a misconfigured pipeline. -
Suggestion: Validate the
gitRefinput and handle the case where it’s empty. For example:const gitRef = (gitRefInput ?? "").trim(); if (!gitRef) { throw new Error("gitRef is missing or invalid."); }
-
Best Practices
-
Test Coverage:
-
File:
scripts/flow/build/versioning-strategy.test.ts -
Issue: While the tests cover the new behavior well, there is no test for an invalid or empty
gitRef. This could result in unhandled edge cases in production if the pipeline configuration is incorrect. -
Suggestion: Add a case in the test suite where
gitRefis missing or invalid to ensure the function handles these gracefully.{ description: "missing gitRef defaults to candidate version", gitVer: "v8.5.0", branches: ["release-8.5"], expect: { version: "v8.5.1-pre", }, },
-
-
Consistency in Logging:
-
File:
scripts/flow/build/versioning-strategy.ts, lines 97-105 -
Issue: The
console.warnandconsole.infomessages are helpful but could benefit from a consistent format. Currently, they differ in tone and verbosity. -
Suggestion: Standardize log messages with a uniform prefix (e.g.,
[VersioningStrategy]) and concise phrasing.console.warn( "[VersioningStrategy] Non-tag build detected. Adjusting released version", normalizedRawVersion, "to candidate version." );
-
Best Practices (Documentation)
- Documentation Completeness:
-
File:
scripts/flow/build/versioning-strategy.md -
Issue: While the document explains the changes well, it does not include an example of how the
--git_refparameter should be used in the CLI. -
Suggestion: Add an example CLI execution command to show how to pass the
--git_refparameter.Example usage: ```bash deno run versioning-strategy.ts --git_version_file=version.txt --contain_branches_file=branches.txt --git_ref=refs/tags/v8.5.0
-
- Follow-up Action Reminder:
-
File: PR Description
-
Issue: While the description mentions a follow-up action, it does not specify where to update the pinned commit (
pingcap-get-set-release-version.yaml). -
Suggestion: Specify the filename in the follow-up section to avoid ambiguity.
**Follow-up required after merge:** Update the pinned commit in `pingcap-get-set-release-version.yaml` to reference the merge commit of this change.
-
Best Practices (Style)
-
Magic Numbers:
-
File:
scripts/flow/build/versioning-strategy.ts, line 101 -
Issue: Adding
1torv.patchis a magic number that could benefit from being a named constant or a function to clarify intent. -
Suggestion: Define a
constor function to represent the increment value.const PATCH_INCREMENT = 1; return { releaseVersion: `v${rv.major}.${rv.minor}.${rv.patch + PATCH_INCREMENT}-pre`, };
-
-
Type Safety:
-
File:
scripts/flow/build/versioning-strategy.ts, line 89 -
Issue: The
gitRefparameter is expected to be a string, but the code handlesnull/undefinedexplicitly withgitRef ?? "". This indicates a potential type mismatch. -
Suggestion: Update the function signature to enforce type safety or handle undefined input properly.
export function compute( rawVersion: string, commitInBranches: string[], gitRef?: string, ): builtControl { const gitRefNormalized = gitRef?.trim() || ""; // ... }
-
Conclusion
The PR is well-structured and effectively addresses the issue with minimal disruption to the existing codebase. Consider addressing the above points, especially the test coverage and logging consistency, to further improve the robustness and maintainability of the implementation.
`compute()` returned a bare GA version as soon as `git describe --tags` parsed as one, before any branch reasoning, and the input carries no information about the ref that triggered the build. A branch pushed at a released commit — a branch cut from `v9.0.0`, for example — produces the same `git describe` output, so the branch-push triggers routed an official release version into the delivered registry and could fabricate or overwrite a released artifact from a ref nobody released. Pass the triggering ref to the computation and treat a released version as a candidate unless that ref is under `refs/tags/`: the next patch with a `pre` prerelease (`v9.0.0` pushed as a branch becomes `v9.0.1-pre`), and no git tag is created, so the following steps cannot mistake the build for a tag build. The ref reaches the script through a new `--git_ref` argument, filled from the `git-ref` pipeline parameter the task already receives; tag triggers bind it to `refs/tags/<tag>` and branch triggers to the short branch name. Verified: - `versioning-strategy.test.ts` gains the branch-push, pull-request and tag-push cases for a released version; the existing rows now state their triggering ref (the tests pass, and the hotfix-anchor rows are unchanged); - `serverless-builds.test.ts` asserts the task forwards `--git_ref`; `deno test -A` on both files is green.
bd92bf6 to
38118fb
Compare
There was a problem hiding this comment.
I have already done a preliminary review for you, and I hope to help you do a better job.
Summary
This PR addresses a critical issue related to the misclassification of build versions by ensuring that only tag-triggered builds report a released version. The fix involves introducing a --git_ref argument to identify the triggering ref and modifying the compute function to distinguish between tag pushes and branch pushes. The changes are well-documented, with updates to the implementation, tests, and documentation. Overall, the PR is structured and tested effectively, but there are a few areas for improvement related to code clarity and edge case handling.
Critical Issues
-
Edge Case: Invalid
git_refInput- File:
versioning-strategy.ts, lines 84-87 - Issue: The
triggeredByTaglogic assumes that thegitRefvalue is always sanitized. IfgitRefcontains unexpected whitespaces or malformed data, the regex check might yield incorrect results. - Suggestion: Sanitize the
gitRefinput to ensure it is properly formatted before validation. For example:const sanitizedGitRef = (gitRef ?? "").trim(); const triggeredByTag = /^refs\/tags\//.test(sanitizedGitRef);
- File:
-
Potential Misclassification of Non-Standard Refs
- File:
versioning-strategy.ts, lines 84-87 - Issue: The regex only checks for
refs/tags/. Non-standard or custom refs that are not explicitly handled could still cause unexpected behavior. - Suggestion: Add stricter validation or log a warning for unexpected
gitRefformats. For example:if (!sanitizedGitRef.startsWith('refs/tags/') && !sanitizedGitRef.startsWith('refs/heads/') && !sanitizedGitRef.startsWith('refs/pull/')) { console.warn(`Unexpected gitRef format: ${sanitizedGitRef}`); }
- File:
Code Improvements
-
Refactor
candidateVersionFunction for Reusability- File:
versioning-strategy.ts, lines 11-14 - Issue: The
candidateVersionfunction is specific to adding a-presuffix for candidate versions but could be generalized for other types of version manipulation. - Suggestion: Refactor the function to accept customizable suffixes or increments. For example:
function modifyVersion(rv: semver.SemVer, suffix: string): builtControl { return { releaseVersion: `v${rv.major}.${rv.minor}.${rv.patch + 1}${suffix}` }; }
- File:
-
Inline Comments in
computeFunction- File:
versioning-strategy.ts, lines 69-107 - Issue: While the logic is sound, the function's flow could be more readable with inline comments explaining key decisions. For example, clarify why
candidateVersionis used in each scenario. - Suggestion: Add concise comments summarizing the rationale for each block.
- File:
Best Practices
-
Missing Validation for CLI Arguments
- File:
versioning-strategy.ts, lines 220-289 - Issue: The
git_refargument is taken at face value without validation. Invalid or missing values could lead to subtle bugs. - Suggestion: Validate CLI arguments and provide meaningful error messages for invalid inputs. For example:
if (!flags.git_ref) { console.error("Error: --git_ref is required for accurate version computation."); Deno.exit(1); }
- File:
-
Testing for Edge Cases
- Files:
versioning-strategy.test.ts,serverless-builds.test.ts - Issue: While the tests cover typical cases, edge cases like invalid
gitRefvalues (e.g., empty strings, unexpected formats) are not explicitly tested. - Suggestion: Add test cases for invalid
gitRefinputs to ensure robust error handling. For example:{ description: "invalid gitRef format", gitVer: "v9.0.0", branches: ["release-9.0"], gitRef: "invalid-ref-format", expect: { version: "v9.0.1-pre", // Should fallback to candidate version }, }
- Files:
-
Documentation Update for CLI Usage
- File:
versioning-strategy.md, lines 3-20 - Issue: While the triggering ref logic is documented, there is no example of how the
--git_refargument should be used in scripts or pipelines. - Suggestion: Include an explicit example of a CLI invocation with the
--git_refargument in the documentation:deno run versioning-strategy.ts --git_version_file=version.txt --contain_branches=release-1.0 --git_ref=refs/tags/v1.0.0Example:
- File:
-
Consistent Naming Convention for Variables
- File:
versioning-strategy.ts - Issue: Variable names like
rv(parsed version) andgitRef(triggering ref) are inconsistent in terms of clarity. - Suggestion: Use more descriptive names such as
parsedVersionandtriggeringReffor better readability.
- File:
By addressing the above issues, the PR can be made more robust and maintainable, ensuring that the changes are both functional and future-proof.
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: wuhuizuo The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
…5565) The version-CLI step runs `scripts/flow/build/versioning-strategy.ts` from a commit-pinned URL (added in #5561), so the fix in #5564 — a released version now requires a tag trigger — only reaches Tekton once the pin moves to it. Move the pin from `10bcc6134c65…` to `32e6febe3b96…`, the merge commit of #5564. Verified: the pinned URL returns `200` and serves the fixed script (it contains the `triggeredByTag` check), and `deno test -A tekton/tests/` passes (37 tests, 0 failures).
Problem
compute()returns a bare GA version as soon asgit describe --tagsparses asone, before any of the branch reasoning:
Its only inputs are
git describe --tags --always --dirtyandgit branch --contains, so it cannot tell a tag push from a branch push at the samecommit. A branch cut from a released tag (or any branch whose head carries a
vX.Y.Ztag) resolves to that released version, and the branch-push triggersroute it into the registry that feeds delivery
(
git-push-branch-build-community-linux.yaml→gcp-classic-build-params) — soan unreleased ref can publish, or overwrite, something that looks like an
official release.
Change
Pass the triggering ref into the computation and only report a released version
when that ref is under
refs/tags/:v9.0.0→v9.0.0(unchanged);v9.0.0→v9.0.1-pre;v9.0.0→v9.0.1-pre.A candidate gets no new git tag, so the steps after this one cannot create a
GA-looking tag in the worktree and treat the build as a tag build.
The ref arrives as a new
--git_refargument, filled from thegit-refpipelineparameter the task already receives: the tag triggers bind it to
refs/tags/<tag>, the branch triggers to the short branch name, and a missingvalue is treated as "not a tag push" (the safe side).
The hotfix release-anchor rows (
v8.5.1-20250101-fecba32on a hotfix branch) aredeliberately unchanged: that naming is product behaviour with its own documented
mitigation.
Verification
versioning-strategy.test.ts: existing rows now state their triggering ref;new rows cover the tag, branch and pull-request cases at a released version.
serverless-builds.test.ts: asserts the task forwards--git_ref.deno test -Aon both files: green (1 passed/11 passed).versioning-strategy.mddocuments the rule.Follow-up required after merge:
pingcap-get-set-release-version.yamlrunsthe script from a commit-pinned URL, so the pin has to move to the merge commit
of this change in a follow-up commit — otherwise the fix is not the code the task
executes.