You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "snazy (via GitHub)" <gi...@apache.org> on 2026/05/15 09:25:11 UTC
[PR] AGENTS.md: improve issue driven work [polaris]
snazy opened a new pull request, #4454:
URL: https://github.com/apache/polaris/pull/4454
Add some explicit instructions to let agents look "around the corner" and reason about the issue before writing any code.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3258929261
##########
AGENTS.md:
##########
@@ -66,6 +66,30 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
+
+A GitHub issue is a starting point for investigation, not an implementation plan.
+Before making an issue-driven change, verify that the requested behavior is still
+missing and that the proposed fix actually addresses the stated problem.
+
+Required workflow:
+
+1. Trace the current code path related to the issue.
+2. Search for existing validation, tests, build tasks, or runtime behavior that may
+ already cover the requested case.
+3. Compare the issue's requested failure modes with the change you intend to make.
+ If the change only addresses part of the issue, use `Related to #NNN`, not
+ `Fixes #NNN`.
+4. Do not add redundant checks. If existing code already fails, validates, or tests
+ the scenario, explain that finding instead of opening a code-change PR.
+5. Do not materialize unbounded inputs just to perform existence checks. Prefer
+ streaming, short-circuiting, indexed lookups, or existing APIs. If collecting is
+ necessary, the bound must be obvious from the code or explained in the PR.
Review Comment:
It took me 30 seconds to understand what you meant by `materialize unbounded inputs` š
- I think it would be beneficial to agents (and humans) to clarify the context here:
> 5. **When streaming results from the database (on any external datasource),** do not materialize unbounded inputs...
But once this clarification is in, I'm not sure that this item belongs in this list: all other items are about validating the issue, but this one is an implementation guideline. I wonder if this item shouldn't be moved to `CONTRIBUTING.md`?
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3259209377
##########
AGENTS.md:
##########
@@ -66,6 +66,30 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
+
+A GitHub issue is a starting point for investigation, not an implementation plan.
+Before making an issue-driven change, verify that the requested behavior is still
+missing and that the proposed fix actually addresses the stated problem.
+
+Required workflow:
+
+1. Trace the current code path related to the issue.
+2. Search for existing validation, tests, build tasks, or runtime behavior that may
+ already cover the requested case.
+3. Compare the issue's requested failure modes with the change you intend to make.
+ If the change only addresses part of the issue, use `Related to #NNN`, not
+ `Fixes #NNN`.
+4. Do not add redundant checks. If existing code already fails, validates, or tests
+ the scenario, explain that finding instead of opening a code-change PR.
+5. Do not materialize unbounded inputs just to perform existence checks. Prefer
+ streaming, short-circuiting, indexed lookups, or existing APIs. If collecting is
+ necessary, the bound must be obvious from the code or explained in the PR.
Review Comment:
Good point. Youāre right that it is an implementation guideline rather than part of validating an issue. Iāve moved it out of this list and clarify the context.
Iād prefer to keep it in AGENTS.md for now under Simplicity, because this PR is about agent guidance.
We can promote it to CONTRIBUTING.md separately if we want it as broader contributor guidance.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3258929261
##########
AGENTS.md:
##########
@@ -66,6 +66,30 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
+
+A GitHub issue is a starting point for investigation, not an implementation plan.
+Before making an issue-driven change, verify that the requested behavior is still
+missing and that the proposed fix actually addresses the stated problem.
+
+Required workflow:
+
+1. Trace the current code path related to the issue.
+2. Search for existing validation, tests, build tasks, or runtime behavior that may
+ already cover the requested case.
+3. Compare the issue's requested failure modes with the change you intend to make.
+ If the change only addresses part of the issue, use `Related to #NNN`, not
+ `Fixes #NNN`.
+4. Do not add redundant checks. If existing code already fails, validates, or tests
+ the scenario, explain that finding instead of opening a code-change PR.
+5. Do not materialize unbounded inputs just to perform existence checks. Prefer
+ streaming, short-circuiting, indexed lookups, or existing APIs. If collecting is
+ necessary, the bound must be obvious from the code or explained in the PR.
Review Comment:
It took me 30 seconds to understand what you meant by `materialize unbounded inputs` š
- I think it would be beneficial to agents (and humans) to clarify the context here:
> 5. **When fetching results from the database (on any external datasource),** do not materialize unbounded inputs...
But once this clarification is in, I'm not sure that this item belongs in this list: all other items are about validating the issue, but this one is an implementation guideline. I wonder if this item shouldn't be moved to `CONTRIBUTING.md`?
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "RussellSpitzer (via GitHub)" <gi...@apache.org>.
RussellSpitzer commented on PR #4454:
URL: https://github.com/apache/polaris/pull/4454#issuecomment-4478699862
This seems a bit more geared towards a personal workflow, are we sure it belongs in the repository's Agent's md?
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #4454:
URL: https://github.com/apache/polaris/pull/4454#issuecomment-4747885200
This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on PR #4454:
URL: https://github.com/apache/polaris/pull/4454#issuecomment-4484998994
Thanks, I see the concern.
Iād prefer to keep the issue-driven guidance as a separate section, because this is a recurring PR pattern, and the section title gives reviewers something concrete to point to.
Folding it into āUnderstand Before Codingā would make the guidance less visible.
For the resource-use paragraph, I agree it is not only about simplicity, but Iām not sure a dedicated IO section is worth it for a single paragraph.
The rule is: choose the simplest resource-friendly implementation instead of, for example, materializing an unbounded source. Iād keep it under Simplicity unless we expect to add more IO/resource guidance later.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3263081319
##########
AGENTS.md:
##########
@@ -229,6 +253,11 @@ Write the minimum code that solves the problem.
Start with the simplest correct implementation. Optimize only when the task
requires it, and only after the simple version works and has tests.
+When reading from a database, object store, filesystem, archive, or other external
+data source, do not materialize unbounded inputs just to perform existence checks.
+Prefer streaming, short-circuiting, indexed lookups, or existing APIs. If collecting
+is necessary, the bound must be obvious from the code or explained in the PR.
Review Comment:
Does it belong to the section of Simplicity? I'd move it to a section like IO handling as a general suggestion.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "RussellSpitzer (via GitHub)" <gi...@apache.org>.
RussellSpitzer commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3259729172
##########
AGENTS.md:
##########
@@ -66,6 +66,27 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
+
+A GitHub issue is a starting point for investigation, not an implementation plan.
+Before making an issue-driven change, verify that the requested behavior is still
+missing and that the proposed fix actually addresses the stated problem.
+
+Required workflow:
+
+1. Trace the current code path related to the issue.
+2. Search for existing validation, tests, build tasks, or runtime behavior that may
+ already cover the requested case.
+3. Compare the issue's requested failure modes with the change you intend to make.
+ If the change only addresses part of the issue, use `Related to #NNN`, not
+ `Fixes #NNN`.
+4. Do not add redundant checks. If existing code already fails, validates, or tests
Review Comment:
This could probably just be added to the above section (Understand before Coding)
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] closed pull request #4454: AGENTS.md: improve issue driven work
URL: https://github.com/apache/polaris/pull/4454
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] AGENTS.md: improve issue driven work [polaris]
Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #4454:
URL: https://github.com/apache/polaris/pull/4454#discussion_r3270083359
##########
AGENTS.md:
##########
@@ -229,6 +253,11 @@ Write the minimum code that solves the problem.
Start with the simplest correct implementation. Optimize only when the task
requires it, and only after the simple version works and has tests.
+When reading from a database, object store, filesystem, archive, or other external
+data source, do not materialize unbounded inputs just to perform existence checks.
+Prefer streaming, short-circuiting, indexed lookups, or existing APIs. If collecting
+is necessary, the bound must be obvious from the code or explained in the PR.
Review Comment:
IMO it's a structural mismatch. The principle ("watch unbounded materialization") is correctness/resource bounds, not simplicity. 2 cents: pull this out of the PR and refile once there are enough resource patterns to form a section, or fold into a future Performance/Design Patterns expansion.
##########
AGENTS.md:
##########
@@ -66,6 +66,27 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
Review Comment:
+1 to Russell. IMO the five-step workflow restates "verify before claiming" with issue-specific detail. A subsection under "Understand Before Coding" would carry the same weight without two top-level sections framed around the same thing.
##########
AGENTS.md:
##########
@@ -66,6 +66,27 @@ assumptions and running with them without checking.
---
+## Do Not Treat Issues As Specifications [DISCIPLINE]
+
+A GitHub issue is a starting point for investigation, not an implementation plan.
+Before making an issue-driven change, verify that the requested behavior is still
+missing and that the proposed fix actually addresses the stated problem.
+
+Required workflow:
+
+1. Trace the current code path related to the issue.
+2. Search for existing validation, tests, build tasks, or runtime behavior that may
+ already cover the requested case.
+3. Compare the issue's requested failure modes with the change you intend to make.
+ If the change only addresses part of the issue, use `Related to #NNN`, not
+ `Fixes #NNN`.
Review Comment:
IMO this is a PR-author convention rather than an agent-coding discipline. AGENTS.md isn't quite the right surface for it. 2 cents: move to CONTRIBUTING.md or the PR template, where the rest of the project's commit/PR conventions live.
##########
AGENTS.md:
##########
@@ -195,6 +216,9 @@ Use the PR template (`.github/pull_request_template.md`). At minimum:
6. If your change affects user-facing behavior or configuration, check whether
`site/content/in-dev/unreleased/` needs updates.
+For issue-driven work, the PR description must explain the current behavior that
+was verified in the codebase and why existing checks do not already cover it.
Review Comment:
I'm skeptical about adding issue-specific PR-description boilerplate here. The general "explain what you verified" expectation is already in this section. Issue-specific boilerplate gets copy-pasted without actually doing the verification, and reviewers can read its presence as proxy for verification. 2 cents: drop and rely on the workflow rule above.
--
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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org