Skip to content

fix(scripts): only a tag push may report a released version - #5564

Merged
ti-chi-bot[bot] merged 1 commit into
mainfrom
fix/versioning-tag-only
Nov 12, 2026
Merged

ti-chi-bot[bot] merged 1 commit into
mainfrom
fix/versioning-tag-only

Conversation

@wuhuizuo

Copy link
Copy Markdown
Contributor

Problem

compute() returns a bare GA version as soon as git describe --tags parses as
one, before any of the branch reasoning:

if (isGaVer(rv)) {
  return { releaseVersion: "v" + semver.format(rv) };
}

Its only inputs are git describe --tags --always --dirty and git branch --contains, so it cannot tell a tag push from a branch push at the same
commit
. A branch cut from a released tag (or any branch whose head carries a
vX.Y.Z tag) resolves to that released version, and the branch-push triggers
route it into the registry that feeds delivery
(git-push-branch-build-community-linux.yaml → gcp-classic-build-params) — so
an 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/:

  • tag push at v9.0.0 → v9.0.0 (unchanged);
  • branch push at v9.0.0 → v9.0.1-pre;
  • pull request at 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_ref argument, filled from the git-ref pipeline
parameter the task already receives: the tag triggers bind it to
refs/tags/<tag>, the branch triggers to the short branch name, and a missing
value is treated as "not a tag push" (the safe side).

The hotfix release-anchor rows (v8.5.1-20250101-fecba32 on a hotfix branch) are
deliberately 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 -A on both files: green (1 passed / 11 passed).
  • versioning-strategy.md documents the rule.

Follow-up required after merge: pingcap-get-set-release-version.yaml runs
the 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.

@ti-chi-bot ti-chi-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 candidateVersion is clear in its intent but could benefit from a more precise name indicating that it adjusts versions for non-tag builds.

    • Suggestion: Consider renaming candidateVersion to something like adjustForNonTagBuilds for 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 "" for gitRef is overly permissive. A missing or invalid gitRef should ideally trigger an explicit error or warning, as it could indicate a misconfigured pipeline.

    • Suggestion: Validate the gitRef input 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 gitRef is 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.warn and console.info messages 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_ref parameter should be used in the CLI.

    • Suggestion: Add an example CLI execution command to show how to pass the --git_ref parameter.

      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 1 to rv.patch is a magic number that could benefit from being a named constant or a function to clarify intent.

    • Suggestion: Define a const or 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 gitRef parameter is expected to be a string, but the code handles null/undefined explicitly with gitRef ?? "". 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.

@ti-chi-bot ti-chi-bot Bot added the size/L label Nov 12, 2026
`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.
@wuhuizuo
wuhuizuo force-pushed the fix/versioning-tag-only branch from bd92bf6 to 38118fb Compare November 12, 2026 11:36

@ti-chi-bot ti-chi-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Edge Case: Invalid git_ref Input

    • File: versioning-strategy.ts, lines 84-87
    • Issue: The triggeredByTag logic assumes that the gitRef value is always sanitized. If gitRef contains unexpected whitespaces or malformed data, the regex check might yield incorrect results.
    • Suggestion: Sanitize the gitRef input to ensure it is properly formatted before validation. For example:
      const sanitizedGitRef = (gitRef ?? "").trim();
      const triggeredByTag = /^refs\/tags\//.test(sanitizedGitRef);
  2. 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 gitRef formats. For example:
      if (!sanitizedGitRef.startsWith('refs/tags/') && !sanitizedGitRef.startsWith('refs/heads/') && !sanitizedGitRef.startsWith('refs/pull/')) {
          console.warn(`Unexpected gitRef format: ${sanitizedGitRef}`);
      }

Code Improvements

  1. Refactor candidateVersion Function for Reusability

    • File: versioning-strategy.ts, lines 11-14
    • Issue: The candidateVersion function is specific to adding a -pre suffix 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}` };
      }
  2. Inline Comments in compute Function

    • 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 candidateVersion is used in each scenario.
    • Suggestion: Add concise comments summarizing the rationale for each block.

Best Practices

  1. Missing Validation for CLI Arguments

    • File: versioning-strategy.ts, lines 220-289
    • Issue: The git_ref argument 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);
      }
  2. Testing for Edge Cases

    • Files: versioning-strategy.test.ts, serverless-builds.test.ts
    • Issue: While the tests cover typical cases, edge cases like invalid gitRef values (e.g., empty strings, unexpected formats) are not explicitly tested.
    • Suggestion: Add test cases for invalid gitRef inputs 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
          },
      }
  3. 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_ref argument should be used in scripts or pipelines.
    • Suggestion: Include an explicit example of a CLI invocation with the --git_ref argument in the documentation:
      Example:
      deno run versioning-strategy.ts --git_version_file=version.txt --contain_branches=release-1.0 --git_ref=refs/tags/v1.0.0
      
      
  4. Consistent Naming Convention for Variables

    • File: versioning-strategy.ts
    • Issue: Variable names like rv (parsed version) and gitRef (triggering ref) are inconsistent in terms of clarity.
    • Suggestion: Use more descriptive names such as parsedVersion and triggeringRef for better readability.

By addressing the above issues, the PR can be made more robust and maintainable, ensuring that the changes are both functional and future-proof.

@wuhuizuo

Copy link
Copy Markdown
Contributor Author

/approve

@ti-chi-bot

ti-chi-bot Bot commented Nov 12, 2026

Copy link
Copy Markdown

[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

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@ti-chi-bot ti-chi-bot Bot added the approved label Nov 12, 2026
@ti-chi-bot
ti-chi-bot Bot merged commit 32e6feb into main Nov 12, 2026
8 checks passed
@ti-chi-bot
ti-chi-bot Bot deleted the fix/versioning-tag-only branch November 12, 2026 11:59
ti-chi-bot Bot pushed a commit that referenced this pull request Nov 12, 2026
…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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

1 participant