OPRUN-4268: Add AGENTS.md to allow agents to make contributions to the codebase #580

rashmigottipati · 2025-12-11T16:26:10Z

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

grokspawn · 2025-12-11T16:30:00Z

openshift/AGENTS.md

+
+---
+
+## Understanding the Rebase Process


Worth including that these processes are crystallized in openshift/operator-framework-tooling?

grokspawn · 2025-12-11T16:30:27Z

openshift/AGENTS.md

+- **Updated** if upstream code has changed in conflicting ways
+- **Maintained** by the OpenShift team indefinitely
+
+**Carry patches should only be added if a change absolutely cannot be accepted upstream.** Every carry patch represents ongoing manual work for the maintainers through every upstream release.


grokspawn · 2025-12-11T16:34:31Z

openshift/AGENTS.md

+
+**When to use:** ONLY during the rebase process itself
+
+**AI tools should NEVER suggest these** in regular pull requests - these are added by maintainers when rebasing to a new upstream version.


ankitathomas

/lgtm

grokspawn · 2025-12-11T16:37:48Z

openshift/AGENTS.md

+1. **Understand the intent:** Is this fixing an OpenShift-specific issue or an upstream bug?
+
+2. **Choose the right approach:**
+   - If it's an upstream bug → Should be fixed in `operator-framework/operator-controller` first, then cherry-picked


Not cherry-picked. The downstream-related tooling should be allowed to execute, replaying commits against our fork of the upstream branch, once that has been fast-forwarded.

grokspawn · 2025-12-11T16:40:14Z

openshift/AGENTS.md

+
+## Enforcement
+
+**Pull requests that do not follow these commit message conventions will be rejected by maintainers.** Every commit must use one of the `UPSTREAM:` prefixes listed above (except for direct upstream commits added during rebase).


I think it is that any PR not following these conventions will fail the CI check by commitchecker (though we've definitely encountered some bugs where it did not!!!).

grokspawn · 2025-12-11T16:43:08Z

openshift/AGENTS.md

+2. **Choose the right approach:**
+   - If it's an upstream bug → Should be fixed in `operator-framework/operator-controller` first, then cherry-picked
+   - If it's OpenShift-specific → Use `UPSTREAM: <carry>:` prefix
+   - If it's generated code → Will be handled by `make manifests` with `UPSTREAM: <drop>:`


I think we want to say that agents should resolve via an UPSTREAM: <drop> PR if and only if (IFF) those changes are needed to resolve current failures, and local re-generation of the content cannot (for example, if multiple PRs influence generated content in ways which cannot be trivially merged).

grokspawn · 2025-12-11T16:44:21Z

openshift/AGENTS.md

+If you identify a bug that affects operator-controller generally (not just OpenShift):
+
+1. **The fix should ideally go to upstream `operator-framework/operator-controller` first**
+2. **Then cherry-pick** to OpenShift using `UPSTREAM: <PR number>:` format


We don't want agents performing this step. Instead it's probably better to say that they should wait for the upstream change to be downstreamed using the $tooling on its scheduled interval.
Otherwise, we're going to end up with a bunch of PR-labeled changes duplicating the work of the bumper.

Generally, we avoid using UPSTREAM: <pr number> because we sync everything from upstream. It would have to be an exceptional case to use UPSTREAM: <pr number>, and in fact, it might be preferred to use UPSTREAM: <drop> because the fix will eventually come down from upstream.

Got it, updated in the latest commit

grokspawn · 2025-12-11T16:44:59Z

openshift/AGENTS.md

+
+1. **The fix should ideally go to upstream `operator-framework/operator-controller` first**
+2. **Then cherry-pick** to OpenShift using `UPSTREAM: <PR number>:` format
+3. **Only use `UPSTREAM: <carry>:`** for truly OpenShift-specific behavior


Suggested change

3. **Only use `UPSTREAM: <carry>:`** for truly OpenShift-specific behavior

3. **Only use `UPSTREAM: <carry>:`** for truly OpenShift-specific behavior for content which is not generated

grokspawn · 2025-12-11T16:46:00Z

openshift/AGENTS.md

+| OpenShift test (OTE) | `UPSTREAM: <carry>:` | ❌ NO - Downstream only |
+| OpenShift integration | `UPSTREAM: <carry>:` | ❌ NO - Downstream only |
+| OpenShift config | `UPSTREAM: <carry>:` | ❌ NO - Downstream only |
+| Remove upstream file | `UPSTREAM: <drop>:` | ❌ NO - Downstream only |


I can't think if a case where we would want to follow this path.

An UPSTREAM: <drop> is generally used as a temporary fix, since it's gone during the next sync.
If we did want to remove an upstream file (e.g. .github directory), it would still be a <carry> commit. However, we try to actually avoid that. The bumper actually deletes some of these files itself with a <drop> because it can handle the process better than trying to carry over a <carry> commit and the conflicts that can create.

grokspawn · 2025-12-11T16:47:33Z

openshift/AGENTS.md

+| OpenShift integration | `UPSTREAM: <carry>:` | ❌ NO - Downstream only |
+| OpenShift config | `UPSTREAM: <carry>:` | ❌ NO - Downstream only |
+| Remove upstream file | `UPSTREAM: <drop>:` | ❌ NO - Downstream only |
+| Generated files | `UPSTREAM: <drop>:` | ❌ NO - Regenerate with `make manifests` |


This contradicts previous guidance here which implies that generated stuff which we need to temporarily resolve until some later PR should use this process.

But it is something we do, and something I have done.

grokspawn · 2025-12-11T16:49:57Z

There's some duplicated and internally contradictory content here. Could you re-run this through claude with a "be concise and consistent" prompt modification? If you also direct it to resolve PR comments then you should be able to get to a happy update in a single step.

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

tmshort · 2025-12-11T18:29:34Z

openshift/AGENTS.md

+| General bug fix | `UPSTREAM: <PR>:` | ✅ YES - Fix upstream, then cherry-pick |
+| General feature | `UPSTREAM: <PR>:` | ✅ YES - Add upstream, then cherry-pick |


This ought to be "Fix upstream, then let the tooling synchronize"

tmshort · 2025-12-11T18:39:41Z

TL;DR: we don't cherry-pick to the main branch. We allow the bumper (in openshift/operator-framework-tooling) synchronize from upstream.

However, cherry-picking would be done on release branches, but since most downstream work is on the main branch, cherry-picking is uncommon.

We would almost never see UPSTREAM: pr-number commits. because they would create a conflict on the next upstream sync. Instead, we might do an UPSTREAM: <drop> commit to pull down a fix early, as it then gets dropped on the next sync.

UPSTREAM: <carry> is used for most changes, and 99% of the time, those changes ought to be limited to the openshift directory. Code outside of the openshift directory should generally not be modified downstream; it should be modified upstream and then synced downstream.

UPSTREAM: <drop> is for temporary commits (e.g. the upstream PR example) that are to be dropped on the next sync. They are used by the bumper to create commits that are easier to recreate than to rebase/cherry-pick. For example: UPSTREAM: <drop>: remove upstream GitHub configuration

EDIT: You updated the file as I was writing this... so looking 👀 again.

tmshort · 2025-12-11T18:41:56Z

openshift/AGENTS.md

+**Upstream Repository:** https://github.com/operator-framework/operator-controller
+
+**Key Constraints for AI Agents:**
+- This fork is **rebased regularly** against upstream (with each upstream release)


Technically, it's done daily, not on upstream releases.

Updated this in the latest commit

ankitathomas

/lgtm

tmshort · 2025-12-11T18:45:34Z

This version is much better. I think I had just one comment on the frequency of the synchronization.

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

tmshort · 2025-12-11T18:48:58Z

/lgtm

joelanford · 2025-12-11T18:55:55Z

openshift/AGENTS.md

+3. **Check upstream first** before fixing bugs - should it go upstream?
+4. **Separate commits:** Never mix code changes with generated files
+5. **Run verification:** `make verify` and `make test-unit` before completion
+6. **Sign commits:** Use `git commit -s` for DCO


There's a difference between signing a commit, and including DCO. -s is DCO. -S is sign cryptographically.

Also, we have root-level DCO file to cover this. So while signing is desired, it's not a required step for DCO. And it isn't cryptographic identity attestation.

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

tmshort · 2025-12-11T19:13:44Z

/lgtm

tmshort · 2025-12-11T19:13:50Z

/approve

openshift-ci · 2025-12-11T19:34:08Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ankitathomas, grokspawn, rashmigottipati, tmshort

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~DOWNSTREAM_OWNERS~~ [grokspawn,tmshort]

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

tmshort · 2025-12-11T19:36:41Z

/label acknowledge-critical-fixes-only

tmshort · 2025-12-11T19:42:34Z

/retitle NO-ISSUE: Add AGENTS.md to allow agents to make contributions to the codebase

openshift-ci-robot · 2025-12-11T19:42:41Z

@rashmigottipati: This pull request explicitly references no jira issue.

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

openshift-ci-robot · 2025-12-11T19:55:54Z

@rashmigottipati: This pull request references OPRUN-4268 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.21.0" version, but no target version was set.

In response to this:

Fixes: OPRUN-4268

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

rashmigottipati · 2025-12-11T19:58:22Z

/refresh

bandrade · 2025-12-11T20:23:16Z

/label qe-approved
/verified by @bandrade

openshift-ci-robot · 2025-12-11T20:23:27Z

@rashmigottipati: This pull request references OPRUN-4268 which is a valid jira issue.

In response to this:

Fixes: OPRUN-4268

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

openshift-ci-robot · 2025-12-11T20:23:28Z

@bandrade: This PR has been marked as verified by @bandrade.

In response to this:

/label qe-approved
/verified by @bandrade

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

openshift-ci · 2025-12-11T22:22:04Z

@rashmigottipati: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

Add AGENTS.md for AI code contributions

e6e31cd

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

openshift-ci bot requested review from joelanford and oceanc80 December 11, 2025 16:27

grokspawn reviewed Dec 11, 2025

View reviewed changes

ankitathomas approved these changes Dec 11, 2025

View reviewed changes

openshift-ci bot assigned ankitathomas Dec 11, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

grokspawn reviewed Dec 11, 2025

View reviewed changes

address review comments through addl prompts

be5f2e9

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

rashmigottipati requested a review from grokspawn December 11, 2025 18:21

tmshort reviewed Dec 11, 2025

View reviewed changes

ankitathomas approved these changes Dec 11, 2025

View reviewed changes

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

addressing some more review comments

7a1d590

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

rashmigottipati force-pushed the add-agents-file branch from 3cc0cef to 7a1d590 Compare December 11, 2025 18:47

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

openshift-ci bot assigned tmshort Dec 11, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

joelanford reviewed Dec 11, 2025

View reviewed changes

remove DCO line

a5388a3

Signed-off-by: Rashmi Gottipati <rgottipa@redhat.com>

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Dec 11, 2025

openshift-ci bot added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Dec 11, 2025

grokspawn approved these changes Dec 11, 2025

View reviewed changes

openshift-ci bot assigned grokspawn Dec 11, 2025

openshift-ci bot added the acknowledge-critical-fixes-only Indicates if the issuer of the label is OK with the policy. label Dec 11, 2025

openshift-ci bot changed the title ~~Add AGENTS.md to allow agents to make contributions to the codebase~~ NO-ISSUE: Add AGENTS.md to allow agents to make contributions to the codebase Dec 11, 2025

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Dec 11, 2025

rashmigottipati changed the title ~~NO-ISSUE: Add AGENTS.md to allow agents to make contributions to the codebase~~ OPRUN-4268: Add AGENTS.md to allow agents to make contributions to the codebase Dec 11, 2025

openshift-ci bot added the qe-approved Signifies that QE has signed off on this PR label Dec 11, 2025

openshift-ci-robot added the verified Signifies that the PR passed pre-merge verification criteria label Dec 11, 2025

openshift-merge-bot bot merged commit 47053e9 into openshift:main Dec 11, 2025
11 checks passed

rashmigottipati deleted the add-agents-file branch December 11, 2025 22:28


		When to use: ONLY during the rebase process itself

		AI tools should NEVER suggest these in regular pull requests - these are added by maintainers when rebasing to a new upstream version.


		## Enforcement

		Pull requests that do not follow these commit message conventions will be rejected by maintainers. Every commit must use one of the `UPSTREAM:` prefixes listed above (except for direct upstream commits added during rebase).

	3. Only use `UPSTREAM: <carry>:` for truly OpenShift-specific behavior
	3. Only use `UPSTREAM: <carry>:` for truly OpenShift-specific behavior for content which is not generated

		\| General bug fix \| `UPSTREAM: <PR>:` \| ✅ YES - Fix upstream, then cherry-pick \|
		\| General feature \| `UPSTREAM: <PR>:` \| ✅ YES - Add upstream, then cherry-pick \|

OPRUN-4268: Add AGENTS.md to allow agents to make contributions to the codebase #580

OPRUN-4268: Add AGENTS.md to allow agents to make contributions to the codebase #580

Conversation

rashmigottipati commented Dec 11, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankitathomas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grokspawn commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmshort commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankitathomas left a comment

Choose a reason for hiding this comment

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

openshift-ci bot commented Dec 11, 2025

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

tmshort commented Dec 11, 2025

Uh oh!

openshift-ci-robot commented Dec 11, 2025

Uh oh!

openshift-ci-robot commented Dec 11, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rashmigottipati commented Dec 11, 2025

Uh oh!

bandrade commented Dec 11, 2025

Uh oh!

openshift-ci-robot commented Dec 11, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

rashmigottipati commented Dec 11, 2025 •

edited by openshift-ci bot

Loading

tmshort commented Dec 11, 2025 •

edited

Loading

openshift-ci-robot commented Dec 11, 2025 •

edited by openshift-ci bot

Loading

openshift-ci-robot commented Dec 11, 2025 •

edited by openshift-ci bot

Loading