docs: Operator Go Versioning Policy

[Fortune-Ndlovu]

Description

Standardizing on our Install Methods Go Version Policy. All input is welcome.

Which issue(s) does this PR fix or relate to

Resolves: https://redhat.atlassian.net/browse/RHIDP-14096

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (5) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: [RHIDP-14096](https://redhat.atlassian.net/browse/RHIDP-14096)

✅ Compliance rules (platform): 18 rules

1. Broken Renovate config link 🐞 Bug ⚙ Maintainability ⭐ New

Description

In docs/go-version-policy.md, the link target (.github/renovate.json) is relative to the docs/
directory and will resolve to docs/.github/renovate.json on GitHub, causing a 404. This makes it
harder for reviewers to navigate to the Renovate config referenced by the policy.

Code

docs/go-version-policy.md[25]

+When the `go` directive is bumped, the `toolchain` directive should be updated to track the latest patch release of the declared version. Both changes are deliberate and tracked via a Jira issue each release cycle (for example, [RHIDP-12020](https://redhat.atlassian.net/browse/RHIDP-12020) tracks the update to Go 1.26). At the same time, the [`constraints.go` setting](https://docs.renovatebot.com/golang/#go-binary-version) in the Renovate configuration at [`.github/renovate.json`](.github/renovate.json) must be updated to match the new `go` directive value. This constraint controls which Go dependency versions Renovate is permitted to propose, and a mismatch will cause Renovate to offer updates that may be incompatible with the declared language version.

Relevance

⭐⭐⭐ High

Docs link correctness fixes are routinely accepted (e.g., added missing docs link in PR #2717; fixed
doc URL mismatch in PR #1325).

PR-#2717
PR-#1325

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The policy doc links to .github/renovate.json using a relative path from within docs/, but the
Renovate config file is located at the repository root under .github/renovate.json, so the
rendered link target is incorrect.

docs/go-version-policy.md[25-25]
.github/renovate.json[1-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/go-version-policy.md` links to the Renovate config as `(.github/renovate.json)`, which is a broken relative link from within the `docs/` directory.

## Issue Context
The Renovate config lives at the repository root under `.github/renovate.json`. GitHub resolves relative links based on the current file’s directory.

## Fix Focus Areas
- docs/go-version-policy.md[25-25]

## Suggested change
Update the link target to a repo-root-relative or correct relative path, e.g. `../.github/renovate.json` (from `docs/`) or `/.github/renovate.json` (repo-root absolute).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Constraints version format mismatch 🐞 Bug ≡ Correctness

Description

docs/go-version-policy.md says Renovate’s constraints.go must match the go directive value, but
the repo currently uses go 1.25.0 in go.mod while Renovate is configured with `constraints.go:
"1.25"`. This wording can mislead maintainers into trying to make these strings exactly identical
instead of matching the intended major.minor language version.

Code

docs/go-version-policy.md[R25-26]

+When the `go` directive is bumped, the `toolchain` directive should be updated to track the latest patch release of the declared version. Both changes are deliberate and tracked via a Jira issue each release cycle (for example, [RHIDP-12020](https://redhat.atlassian.net/browse/RHIDP-12020) tracks the update to Go 1.26). At the same time, the `constraints.go` setting in the Renovate configuration at `.github/renovate.json` must be updated to match the new `go` directive value. This constraint controls which Go dependency versions Renovate is permitted to propose, and a mismatch will cause Renovate to offer updates that are incompatible with the declared language version.
+

Relevance

⭐⭐⭐ High

Team already discussed Go version string formats (go 1.25 vs 1.25.0); doc clarification likely
welcomed.

PR-#2127

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The policy mandates matching values, but the repo configuration demonstrates that go.mod and
Renovate constraints intentionally use different string formats for the same Go language version.

docs/go-version-policy.md[25-26]
go.mod[3-6]
.github/renovate.json[17-19]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The policy text implies exact equality between `go.mod`'s `go` directive and Renovate's `constraints.go`, but the repository uses different formats (`1.25.0` vs `1.25`). This can cause confusion during future version bumps.

## Issue Context
- `go.mod` uses a patch-qualified `go` directive.
- Renovate constraints are currently configured as major.minor.

## Fix Focus Areas
- docs/go-version-policy.md[25-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Internal Jira links 🐞 Bug ⚙ Maintainability

Description

The new policy document links RHIDP tickets to redhat.atlassian.net, while this repository otherwise
points contributors to the public issues.redhat.com tracker. This creates inconsistent and
potentially inaccessible references for readers who don’t have access to the Atlassian instance.

Code

docs/go-version-policy.md[25]

+When the `go` directive is bumped, the `toolchain` directive should be updated to track the latest patch release of the declared version. Both changes are deliberate and tracked via a Jira issue each release cycle (for example, [RHIDP-12020](https://redhat.atlassian.net/browse/RHIDP-12020) tracks the update to Go 1.26). At the same time, the `constraints.go` setting in the Renovate configuration at `.github/renovate.json` must be updated to match the new `go` directive value. This constraint controls which Go dependency versions Renovate is permitted to propose, and a mismatch will cause Renovate to offer updates that are incompatible with the declared language version.

Relevance

⭐⭐ Medium

Team removed inaccessible internal links before (PR #955), but no prior reviews about replacing Jira
atlassian links in docs.

PR-#955

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The policy doc introduces multiple redhat.atlassian.net RHIDP references, while the repository’s
README points contributors to issues.redhat.com for RHIDP tracking, indicating the intended
public-facing tracker convention.

docs/go-version-policy.md[25-26]
docs/go-version-policy.md[77-77]
docs/go-version-policy.md[118-118]
README.md[84-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/go-version-policy.md` references RHIDP tickets using `https://redhat.atlassian.net/browse/...`, but the repository’s contributor guidance uses `https://issues.redhat.com/browse/RHIDP`.

This inconsistency can make the references harder to use for readers without Atlassian access and diverges from the repo’s existing convention.

### Issue Context
- The repo README directs issue reporting/browsing to `issues.redhat.com`.
- The new doc includes multiple RHIDP links using `redhat.atlassian.net`.

### Fix Focus Areas
- docs/go-version-policy.md[25-26]
- docs/go-version-policy.md[77-77]
- docs/go-version-policy.md[118-118]

### Suggested fix
Replace `https://redhat.atlassian.net/browse/RHIDP-####` with `https://issues.redhat.com/browse/RHIDP-####` (or remove hyperlinking and keep the ticket IDs as plain text, if preferred).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Missing EOF newline 🐞 Bug ⚙ Maintainability

Description

docs/go-version-policy.md is added without a trailing newline, which can cause noisy diffs and can
fail strict formatting checks. Add a final newline to the file.

Code

docs/go-version-policy.md[118]

+- [RHIDP-14096](https://redhat.atlassian.net/browse/RHIDP-14096) — the Jira issue that prompted this policy document

Relevance

⭐⭐ Medium

No clear historical evidence on enforcing trailing newline in docs; could be treated as low-priority
nit.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR diff marks the new file with No newline at end of file, indicating the final newline is
missing.

docs/go-version-policy.md[118-118]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The markdown file is missing a trailing newline at end-of-file.

## Issue Context
The PR diff explicitly flags this with `\\ No newline at end of file`.

## Fix Focus Areas
- docs/go-version-policy.md[118-118]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. go-toolset tag format mismatch 🐞 Bug ⚙ Maintainability

Description

The policy describes go-toolset tags as containing an RHEL minor component (e.g., 9.7 → 9.8) and
implies reviewers will see that in PR diffs, but this repo’s Dockerfile pins go-toolset with a
numeric tag (e.g., 1781070178). This makes the guidance about interpreting tag changes misleading
for this repository’s actual diffs.

Code

docs/go-version-policy.md[R61-62]

+Docker base image updates to the go-toolset image are classified by Renovate as minor updates when the RHEL version component of the tag changes (for example, `9.7` to `9.8`). However, a Docker minor update can carry a major Go version change inside the image. The go-toolset `9.7` image shipped Go 1.25, while go-toolset `9.8` ships Go 1.26. The pull request diff will only show the image tag and digest change; it will not indicate the Go version change. Reviewers must check the Go version inside the image before approving, using the `skopeo inspect` command described in the Verification section below.
+

Relevance

⭐ Low

Repo Dockerfile updates typically use tags with RHEL minor prefix (e.g., 9.7-…); doc’s 9.7→9.8
example fits.

PR-#2486
PR-#2825

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The doc’s examples and classification discussion are based on 9.x style tags, while the repo’s
Dockerfile uses a numeric tag, so the described review signals won’t appear in this repository’s
Dockerfile diffs.

docs/go-version-policy.md[61-62]
docs/go-version-policy.md[15-16]
Dockerfile[3-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The document’s examples and review guidance assume go-toolset tags encode the RHEL minor (9.x), but the repository’s Dockerfile uses numeric tags, so reviewers cannot infer RHEL minor changes from the tag.

## Issue Context
The policy already recommends verifying the Go version via `skopeo inspect`; update the tag discussion/examples to match what reviewers will actually see in this repo.

## Fix Focus Areas
- docs/go-version-policy.md[61-62]
- docs/go-version-policy.md[15-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Previous review results

Review updated until commit c0afb3b

Results up to commit e483b82

🐞 Bugs (3) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Constraints version format mismatch 🐞 Bug ≡ Correctness

Description

docs/go-version-policy.md says Renovate’s constraints.go must match the go directive value, but
the repo currently uses go 1.25.0 in go.mod while Renovate is configured with `constraints.go:
"1.25"`. This wording can mislead maintainers into trying to make these strings exactly identical
instead of matching the intended major.minor language version.

Code

docs/go-version-policy.md[R25-26]

+When the `go` directive is bumped, the `toolchain` directive should be updated to track the latest patch release of the declared version. Both changes are deliberate and tracked via a Jira issue each release cycle (for example, [RHIDP-12020](https://redhat.atlassian.net/browse/RHIDP-12020) tracks the update to Go 1.26). At the same time, the `constraints.go` setting in the Renovate configuration at `.github/renovate.json` must be updated to match the new `go` directive value. This constraint controls which Go dependency versions Renovate is permitted to propose, and a mismatch will cause Renovate to offer updates that are incompatible with the declared language version.
+

Relevance

⭐⭐⭐ High

Team already discussed Go version string formats (go 1.25 vs 1.25.0); doc clarification likely
welcomed.

PR-#2127

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The policy mandates matching values, but the repo configuration demonstrates that go.mod and
Renovate constraints intentionally use different string formats for the same Go language version.

docs/go-version-policy.md[25-26]
go.mod[3-6]
.github/renovate.json[17-19]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The policy text implies exact equality between `go.mod`'s `go` directive and Renovate's `constraints.go`, but the repository uses different formats (`1.25.0` vs `1.25`). This can cause confusion during future version bumps.

## Issue Context
- `go.mod` uses a patch-qualified `go` directive.
- Renovate constraints are currently configured as major.minor.

## Fix Focus Areas
- docs/go-version-policy.md[25-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Missing EOF newline 🐞 Bug ⚙ Maintainability

Description

docs/go-version-policy.md is added without a trailing newline, which can cause noisy diffs and can
fail strict formatting checks. Add a final newline to the file.

Code

docs/go-version-policy.md[118]

+- [RHIDP-14096](https://redhat.atlassian.net/browse/RHIDP-14096) — the Jira issue that prompted this policy document

Relevance

⭐⭐ Medium

No clear historical evidence on enforcing trailing newline in docs; could be treated as low-priority
nit.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR diff marks the new file with No newline at end of file, indicating the final newline is
missing.

docs/go-version-policy.md[118-118]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The markdown file is missing a trailing newline at end-of-file.

## Issue Context
The PR diff explicitly flags this with `\\ No newline at end of file`.

## Fix Focus Areas
- docs/go-version-policy.md[118-118]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. go-toolset tag format mismatch 🐞 Bug ⚙ Maintainability

Description

The policy describes go-toolset tags as containing an RHEL minor component (e.g., 9.7 → 9.8) and
implies reviewers will see that in PR diffs, but this repo’s Dockerfile pins go-toolset with a
numeric tag (e.g., 1781070178). This makes the guidance about interpreting tag changes misleading
for this repository’s actual diffs.

Code

docs/go-version-policy.md[R61-62]

+Docker base image updates to the go-toolset image are classified by Renovate as minor updates when the RHEL version component of the tag changes (for example, `9.7` to `9.8`). However, a Docker minor update can carry a major Go version change inside the image. The go-toolset `9.7` image shipped Go 1.25, while go-toolset `9.8` ships Go 1.26. The pull request diff will only show the image tag and digest change; it will not indicate the Go version change. Reviewers must check the Go version inside the image before approving, using the `skopeo inspect` command described in the Verification section below.
+

Relevance

⭐ Low

Repo Dockerfile updates typically use tags with RHEL minor prefix (e.g., 9.7-…); doc’s 9.7→9.8
example fits.

PR-#2486
PR-#2825

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The doc’s examples and classification discussion are based on 9.x style tags, while the repo’s
Dockerfile uses a numeric tag, so the described review signals won’t appear in this repository’s
Dockerfile diffs.

docs/go-version-policy.md[61-62]
docs/go-version-policy.md[15-16]
Dockerfile[3-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The document’s examples and review guidance assume go-toolset tags encode the RHEL minor (9.x), but the repository’s Dockerfile uses numeric tags, so reviewers cannot infer RHEL minor changes from the tag.

## Issue Context
The policy already recommends verifying the Go version via `skopeo inspect`; update the tag discussion/examples to match what reviewers will actually see in this repo.

## Fix Focus Areas
- docs/go-version-policy.md[61-62]
- docs/go-version-policy.md[15-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit e483b82

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Internal Jira links 🐞 Bug ⚙ Maintainability

Description

The new policy document links RHIDP tickets to redhat.atlassian.net, while this repository otherwise
points contributors to the public issues.redhat.com tracker. This creates inconsistent and
potentially inaccessible references for readers who don’t have access to the Atlassian instance.

Code

docs/go-version-policy.md[25]

+When the `go` directive is bumped, the `toolchain` directive should be updated to track the latest patch release of the declared version. Both changes are deliberate and tracked via a Jira issue each release cycle (for example, [RHIDP-12020](https://redhat.atlassian.net/browse/RHIDP-12020) tracks the update to Go 1.26). At the same time, the `constraints.go` setting in the Renovate configuration at `.github/renovate.json` must be updated to match the new `go` directive value. This constraint controls which Go dependency versions Renovate is permitted to propose, and a mismatch will cause Renovate to offer updates that are incompatible with the declared language version.

Relevance

⭐⭐ Medium

Team removed inaccessible internal links before (PR #955), but no prior reviews about replacing Jira
atlassian links in docs.

PR-#955

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The policy doc introduces multiple redhat.atlassian.net RHIDP references, while the repository’s
README points contributors to issues.redhat.com for RHIDP tracking, indicating the intended
public-facing tracker convention.

docs/go-version-policy.md[25-26]
docs/go-version-policy.md[77-77]
docs/go-version-policy.md[118-118]
README.md[84-87]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/go-version-policy.md` references RHIDP tickets using `https://redhat.atlassian.net/browse/...`, but the repository’s contributor guidance uses `https://issues.redhat.com/browse/RHIDP`.

This inconsistency can make the references harder to use for readers without Atlassian access and diverges from the repo’s existing convention.

### Issue Context
- The repo README directs issue reporting/browsing to `issues.redhat.com`.
- The new doc includes multiple RHIDP links using `redhat.atlassian.net`.

### Fix Focus Areas
- docs/go-version-policy.md[25-26]
- docs/go-version-policy.md[77-77]
- docs/go-version-policy.md[118-118]

### Suggested fix
Replace `https://redhat.atlassian.net/browse/RHIDP-####` with `https://issues.redhat.com/browse/RHIDP-####` (or remove hyperlinking and keep the ticket IDs as plain text, if preferred).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[rhdh-qodo-merge]

PR Summary by Qodo

Document Go versioning policy for rhdh-operator install methods
📝 Documentation 🕐 20-40 Minutes

Walkthroughs

Description

• Add a written Go versioning policy for rhdh-operator maintainers and reviewers.
• Clarify update rules for go.mod, toolchain, go-toolset images, and Renovate constraints.
• Provide concrete verification commands for confirming Go versions in images and binaries.

Diagram

graph TD
  A([Maintainers/Reviewers]) --> B["Go version policy doc"] --> C["go.mod (go/toolchain)"] --> G["Operator binary/image"]
  B --> D[".github/renovate.json (constraints.go)"] --> C
  B --> E["Dockerfile (builder FROM)"] --> F[("UBI go-toolset image")] --> G

  subgraph Legend
    direction LR
    _h([Human]) ~~~ _f["Config/doc file"] ~~~ _img[("Build image")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add CI guardrails to enforce policy invariants

• ➕ Prevents drift between go.mod and Renovate constraints.go automatically
• ➕ Catches accidental go directive bumps on release branches early
• ➕ Reduces reviewer burden for repetitive checks
• ➖ Requires implementing and maintaining CI logic/rules
• ➖ May need branch-aware behavior (main vs release) to avoid false positives

2. Capture as an ADR / release-process doc alongside existing workflows

• ➕ Makes it part of the formal decision record and release playbook
• ➕ Easier discoverability for new maintainers if linked from contributing docs
• ➖ More process overhead than a standalone doc
• ➖ Still doesn’t enforce correctness without automation

Recommendation: The PR’s approach (a dedicated, explicit policy document) is the right first step because the behavior depends on multiple independently-versioned controls (go.mod directives, go-toolset image, Renovate constraints). As follow-ups, consider adding a lightweight CI check to ensure constraints.go matches the go directive on each branch and to prevent unintended release-branch directive bumps.

File Changes

Documentation (1)

go-version-policy.md Add Go versioning policy and verification guidance +118/-0

Add Go versioning policy and verification guidance

• Introduces a policy document that defines how and when to update the 'go'/'toolchain' directives, the go-toolset Docker builder image, and Renovate’s 'constraints.go' on main vs release branches. Includes reviewer guidance for Renovate PRs and commands to verify the Go version in go-toolset images and shipped operator binaries.

docs/go-version-policy.md

---

[Fortune-Ndlovu]

/cc @rm3l

[rm3l]

Looks great overall and aligns with what was requested in https://redhat.atlassian.net/browse/RHIDP-14096. A few comments.

[rm3l]

/agentic_review

[rhdh-qodo-merge]

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again

[rm3l]

/agentic_review

[rhdh-qodo-merge]

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again

[gazarenkov]

/agentic_review

[rhdh-qodo-merge]

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again

[rm3l]

/agentic_review

[rhdh-qodo-merge]

Code review by qodo was updated up to the latest commit e483b82

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Fortune-Ndlovu]

hey @rm3l The PR checks are failing because actions/checkout was upgraded to v7 in #3031, which now blocks checking out fork PR code in pull_request_target workflows by default. The error is:

Error: Refusing to check out fork pull request code from a 'pull_request_target' workflow. This workflow runs with the base repository's GITHUB_TOKEN, secrets, default-branch cache scope, and runner access. Fetching and executing a fork's code in that trusted context commonly leads to "pwn request" vulnerabilities. To opt in, review the risks at https://gh.io/securely-using-pull_request_target and set 'allow-unsafe-pr-checkout: true' on the actions/checkout step.

This only affects fork-based PRs, same-repo PRs (like Renovate's) pass fine. The existing authorize job already gates untrusted forks behind manual approval, so adding allow-unsafe-pr-checkout: true to the checkout steps in the three affected workflows should be safe. In the meantime, any thoughts on this?

[Fortune-Ndlovu]

/agentic_review

[rhdh-qodo-merge]

Code review by qodo was updated up to the latest commit c0afb3b