It's not about the feature, but about acceptable use in our community and capturing the community's understanding. Different communities might have different "social agreement" here.
What one community agrees is acceptable, another might disagree with. Put yourself in the shoes of someone who contributes to several projects. I personally contributed to about a 100 different projects (in and out ASF) - in the next 3 months. And I could only do this properly without getting push back or some "ivory tower" people telling me, "But 3 years ago we discussed it and we agreed it is fine," coming and scolding me for not following rules discussed in a random discussion 3 years ago. And yes - it happened in Airflow a few times that people were scolded for not following the rules that were not captured in contributions guide. J On Thu, Oct 8, 2026 at 5:16 PM Ash Berlin-Taylor <[email protected]> wrote: > > https://docs.github.com/en/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork > > There you go, docs. Like I said, it’s a GH feature. They ticked the box, they > let us do it. > > And has anyone been surprised so far? > > > > On 8 Oct 2026, at 16:06, Jarek Potiuk <[email protected]> wrote: > > > >> Put most directly: what would someone do differently having this > > information, vs if they didn’t have it? > > > > They would not be surprised and raise their concerns - or if they did we > > would direct them to the docs. > > > > On Thu, Oct 8, 2026 at 4:58 PM Ash Berlin-Taylor <[email protected]> wrote: > > > >> Put most directly: what would someone do differently having this > >> information, vs if they didn’t have it? > >> > >> This simply doesn’t need documenting, because it’s not something _we as a > >> project_ do. It’s something some maintainers might do when they feel like > >> it or choose to. > >> > >> None of the other things you mention below are even remotely similar to > >> this. > >> > >> Editing a document isn’t done when there’s nothing left to add, it’s done > >> when there is nothing left to take away. > >> > >> > >>> On 7 Oct 2026, at 14:27, Jarek Potiuk <[email protected]> wrote: > >>> > >>> Hi Ash and others, > >>> > >>>> Why does it need documenting? Our docs are already way, way WAY too > >> long. > >>> > >>> Tl;DR; Mostly to document "Whys" rather than follow cargo-cult rules that > >>> result from the whys - and make it easier to adapt them in the future. > >>> > >>> Without documentation, neither AI agents nor new contributors will know > >> why > >>> we are doing things and will continue rediscovering decisions we > >>> already discussed and agreed upon. This makes it difficult to challenge > >> the > >>> rules when better ways to follow the "whys" emerge in the future. > >>> > >>> In my view, our documentation is still not comprehensive enough (and > >> never > >>> will be) comprehensive enough and has a number of gaps in our > >>> "institutional" knowledge Capturing this knowledge—and ensuring it is > >>> searchable, unambiguous, and maintained—allows us to align on basics and > >>> focus on higher-level discussions. > >>> > >>> We have already seen this pay off with our recent agentic work. The ADRs > >>> and guidelines maintainers added have significantly improved PR quality, > >> as > >>> I tracked and clearly saw in my triage trials. > >>> > >>> With agents continuously keeping things in check, contributors no longer > >>> need to manually search through extensive documentation—a common claim - > >>> mostly true in the past: "nobody reads the docs.". People may read even > >>> less docs today, but their agents read and follow it, often explain them > >>> why they do things they do - after reading that in our docs - which is a > >>> classic "learn by doing" pattern. This reduces guesswork and frustration > >>> for new contributors. Instead of asking "Is this fine?" (or more > >> frequently > >>> being scolded for a rule they did not know existed), they can straight > >> away > >>> find out "Why are we doing this?", and when they see a place for > >>> improvement, they might challenge the way - or simply implement new ways > >> by > >>> following the whys -out spending much time with fighting the status quo. > >>> > >>> And then - they can ask even more - and more important - "why" questions. > >>> When those "why" questions arise, documenting the answers prevents us > >> from > >>> having to get them asked and answer, freeing up space for more impactful > >>> discussions. > >>> > >>> Without documenting the reasoning behind our decisions, we risk getting > >>> stuck in cargo-cult patterns where rules are followed without > >> understanding > >>> why. Documenting "why" gives new contributors the context they need to > >>> constructively challenge existing processes. And this is the only way we > >>> can grow: by continuously challenging and rediscovering better ways of > >>> doing things. > >>> > >>> We saw this exact pattern with the introduction of Black, pre-commit > >> hooks, > >>> and CI rules. We used to spend time arguing over formatting and import > >>> styles. Now, these are automated, and our contribution guides explain the > >>> "why" behind them rather than just enforcing the "how." > >>> > >>> This context also allows agents to fix issues autonomously and update > >>> documentation when parameters change for example or when tools get new > >>> capabilities - because they know "why" and can implement fixes and > >> propose > >>> improvements on their own - if the particular captured "tool call" gets > >>> wrong (happens all the time with our release processes now) - for example > >>> happened recently when flit got upgraded to version 4, agents found out > >> and > >>> fixed the issue, updated the docs, tested and compared the packages > >> before > >>> and after - without me asking them for it. All that because our release > >>> docs and breeze docs explained "what" we want to achieve and "why" - the > >>> "how" could be changed autonomously by the agent in the event of external > >>> environment change. > >>> > >>> Documenting our decisions, the rationale behind them, rejected > >>> alternatives, and exception boundaries has successfully eliminated > >>> repetitive debates in the past (which I defeinitely do not miss) and > >> opened > >>> us up for new, more important discussions, and we should continue this > >>> approach. Get better every single day - mostly by documenting and > >>> automating what is important today, so that we make space for things that > >>> will come tomorrow. > >>> > >>> Best regards, > >>> Jarek > >>> > >>> > >>> On Wed, Oct 7, 2026 at 1:28 PM Ash Berlin-Taylor <[email protected]> wrote: > >>> > >>>> Ah, so now here’s the possible point of contention: > >>>> > >>>> Why does it need documenting? Our docs are already way, way WAY too > >> long. > >>>> > >>>> I’ve been doing this _for years_. It’s up to the reviewer, and is a > >>>> natural part of GH PRs. > >>>> > >>>> -ash > >>>> > >>>>> On 7 Oct 2026, at 12:13, Jarek Potiuk <[email protected]> wrote: > >>>>> > >>>>> Thanks for the feedback everyone ! > >>>>> > >>>>> Since this seems non-controversial (surprisingly) I will later today or > >>>>> tomorrow capture it in our contrbuting docs - so that our contributors > >>>> are > >>>>> not surprised by it (or at least we can direct them to it). I will open > >>>> PR > >>>>> later. > >>>>> > >>>>> > >>>>> On Wed, Oct 7, 2026, 11:42 Jarek Potiuk <[email protected]> wrote: > >>>>> > >>>>>> > >>>>>> > >>>>>> On Wed, Oct 7, 2026, 11:19 Natanel <[email protected]> wrote: > >>>>>> > >>>>>>> I think it's a very good idea, what we usually do (at our org) is > >> that > >>>> for > >>>>>>> small and minor changes, the reviewer adds suggestions, and the PR > >>>> owner > >>>>>>> can accept if he agrees, this also solves the org policy issue IMO, > >>>> maybe > >>>>>>> a > >>>>>>> good start is to encourage reviewers to leave suggestions for small > >>>>>>> changes > >>>>>>> rather than comments. > >>>>>>> > >>>>>> > >>>>>> Oh absolutely :). I think this is the 'gradation': comment/ online > >>>> comment > >>>>>> (blocking unless resolved currently) / inline comment with suggestion > >> / > >>>>>> direct fixup. > >>>>>> > >>>>>> And we should IMHO choose whatever is appropriate depending on 'scope' > >>>> of > >>>>>> fix and urgency of the PR - for example I am.much more info fixups > >> just > >>>>>> before preparing provider's release. > >>>>>> > >>>>>> > >>>>>> > >>>>>> > >>>>>> > >>>>>>> It is limited to small changes, but from my point of view, an "almost > >>>>>>> done" > >>>>>>> pr only needs minor fixups. > >>>>>>> In case the PR owner does not reply and the PR is stale this might > >> not > >>>>>>> work, yet I think users with read access should be able to accept > >> those > >>>>>>> suggestions as well > >>>>>>> > >>>>>>> Any thoughts about this proposal? > >>>>>>> > >>>>>>> > >>>>>>> On Wed, Oct 7, 2026, 11:59 Ash Berlin-Taylor <[email protected]> wrote: > >>>>>>> > >>>>>>>> Org policy prevents us from changing this I think. Or at least I > >> have > >>>>>>>> never been able to find a setting that changes this :( > >>>>>>>> > >>>>>>>>> On 6 Oct 2026, at 17:52, Jarek Potiuk <[email protected]> wrote: > >>>>>>>>> > >>>>>>>>>> Plus isn’t this a configurable setting? i.e. when I open a PR from > >>>> my > >>>>>>>> fork I can “allow edits from maintainers” < > >>>>>>>> > >>>>>>> > >>>> > >> https://docs.github.com/en/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork > >>>>>>>> , > >>>>>>>> and you could argue I’m opting into this approach by checking that > >>>> box. > >>>>>>>>> > >>>>>>>>> Yes. It is. For example all astronomer people contributing from > >>>>>>>>> astronomer repo have it disabled :D > >>>>>>>>> > >>>>>>>>> On Tue, Oct 6, 2026 at 6:47 PM Julian LaNeve via dev > >>>>>>>>> <[email protected]> wrote: > >>>>>>>>>> > >>>>>>>>>> This may be a personal thing but when I’ve made contributions to > >>>>>>> other > >>>>>>>> OSS projects I generally care more about getting the change in than > >> I > >>>> am > >>>>>>>> attached to my particular code / implementation. So I always look at > >>>> it > >>>>>>> as > >>>>>>>> a win-win when someone takes my contribution and runs with it - I > >> can > >>>>>>>> always go back and look at the changes to learn if I want. > >>>>>>>>>> > >>>>>>>>>> Plus isn’t this a configurable setting? i.e. when I open a PR from > >>>> my > >>>>>>>> fork I can “allow edits from maintainers” < > >>>>>>>> > >>>>>>> > >>>> > >> https://docs.github.com/en/pull-requests/how-tos/work-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork > >>>>>>>> , > >>>>>>>> and you could argue I’m opting into this approach by checking that > >>>> box. > >>>>>>>>>> > >>>>>>>>>>> On Oct 6, 2026, at 12:40 PM, Jarek Potiuk <[email protected]> > >>>> wrote: > >>>>>>>>>>> > >>>>>>>>>>> Just to share my experience - I think I did it many times (more > >>>> than > >>>>>>>>>>> 50) and never got any push-back. But of course that might be > >>>> because > >>>>>>>>>>> people are shy / afraid to oppose me (I have a reputation for > >> being > >>>>>>>>>>> difficult). > >>>>>>>>>>> But when you think about it, there is no big **issue**: > >>>>>>>>>>> > >>>>>>>>>>> * merging means that is no longer **author's code** - it becomes > >>>>>>>>>>> "community code" > >>>>>>>>>>> * maintainer's job is to make sure that the code is good and > >>>>>>>>>>> maintainable (this approach makes it works) > >>>>>>>>>>> * authorship remains - but also it's there is a co-author (this > >> is > >>>>>>>>>>> what is recorded in commit) > >>>>>>>>>>> * if the committer does not agree with author, they can merge > >>>> follow > >>>>>>>>>>> up commit changing things anyway > >>>>>>>>>>> > >>>>>>>>>>> So - putting aside some possible personal ("it's my own, my > >>>>>>> precious") > >>>>>>>>>>> approach - I see no disadvantages of such an approach. > >>>>>>>>>>> > >>>>>>>>>>> J. > >>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>>> On Tue, Oct 6, 2026 at 6:28 PM Ferruzzi, Dennis via dev > >>>>>>>>>>> <[email protected]> wrote: > >>>>>>>>>>>> > >>>>>>>>>>>> I've definitely considered it, but have not yet done it. I > >> think > >>>>>>> I'm > >>>>>>>> concerned that the contributor may take it the wrong way rather than > >>>> "I > >>>>>>>> just fixed it while I was in there" and "it took just as long to fix > >>>> it > >>>>>>> as > >>>>>>>> it would have taken to explain it". > >>>>>>>>>>>> > >>>>>>>>>>>> - ferruzzi > >>>>>>>>>>>> ________________________________ > >>>>>>>>>>>> From: Jarek Potiuk <[email protected]> > >>>>>>>>>>>> Sent: Tuesday, October 6, 2026 1:17 AM > >>>>>>>>>>>> To: [email protected] <[email protected]> > >>>>>>>>>>>> Subject: [EXT] [DISCUSS] Merging "almost" ready PRs with > >>>>>>>> maintainer-fixups from contributors > >>>>>>>>>>>> > >>>>>>>>>>>> CAUTION: This email originated from outside of the organization. > >>>> Do > >>>>>>>> not click links or open attachments unless you can confirm the > >> sender > >>>>>>> and > >>>>>>>> know the content is safe. > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>>> AVERTISSEMENT: Ce courrier électronique provient d’un expéditeur > >>>>>>>> externe. Ne cliquez sur aucun lien et n’ouvrez aucune pièce jointe > >> si > >>>>>>> vous > >>>>>>>> ne pouvez pas confirmer l’identité de l’expéditeur et si vous n’êtes > >>>> pas > >>>>>>>> certain que le contenu ne présente aucun risque. > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>>> Hello everyone, > >>>>>>>>>>>> > >>>>>>>>>>>> In order to improve our "agentic AI" workflows, I have recently > >>>>>>>>>>>> changed my approach for pull requests that are "almost ready" > >> and > >>>>>>> need > >>>>>>>>>>>> only small fixes, such as mechanical conflicts, typos, or minor > >>>>>>>>>>>> comment updates. I would love to get your feedback on this > >>>> pattern. > >>>>>>>>>>>> > >>>>>>>>>>>> Previously, when a PR had one or two minor issues, I would > >> approve > >>>>>>> it, > >>>>>>>>>>>> add inline comments specifying the necessary changes, and ask > >> the > >>>>>>>>>>>> author to fix them. Recently, I have often adopted this approach > >>>>>>>>>>>> instead: > >>>>>>>>>>>> > >>>>>>>>>>>> - Make inline comments explaining the issue > >>>>>>>>>>>> - Rebase and remove conflicts if needed > >>>>>>>>>>>> - Apply the fixup myself (pushing directly to the contributor's > >>>>>>>> branch). > >>>>>>>>>>>> - Comment and resolve my own inline comments. > >>>>>>>>>>>> - Approve and merge once CI checks pass. > >>>>>>>>>>>> > >>>>>>>>>>>> I only do this for small gaps, edge cases, mechanical fixes, or > >>>>>>>>>>>> documentation updates that do not alter the substance of the PR. > >>>>>>> The > >>>>>>>>>>>> PR remains primarily the author's work, with minor co-authored > >>>>>>> fixes. > >>>>>>>>>>>> > >>>>>>>>>>>> This pattern offers several benefits: > >>>>>>>>>>>> > >>>>>>>>>>>> - Efficiency: With agentic-assisted reviews, the AI already has > >>>> the > >>>>>>>>>>>> context and proposed fix, taking only seconds to apply and push. > >>>>>>>>>>>> - Faster Merges: Eliminates additional review roundtrips and > >>>> avoids > >>>>>>>>>>>> new conflicts from interim merges. > >>>>>>>>>>>> - Fewer Iterations: Prevents extra back-and-forth if a comment > >> is > >>>>>>>>>>>> misunderstood or incompletely fixed. > >>>>>>>>>>>> - Keeps Educational Value: The author receives both an > >> explanation > >>>>>>>>>>>> of the issue and code for the solution. > >>>>>>>>>>>> - PR Capacity: Frees up contributor PR slots sooner. > >>>>>>>>>>>> - Throughput: Helps us process a higher volume of PRs more > >>>> quickly. > >>>>>>>>>>>> > >>>>>>>>>>>> The main tradeoff is that the author learns by reading rather > >> than > >>>>>>>>>>>> doing, which could potentially lead to a more relaxed approach > >> to > >>>>>>>>>>>> minor details. However, if restricted strictly to minor, > >>>> mechanical > >>>>>>>>>>>> adjustments—while still using "Request Changes" for larger > >> gaps—I > >>>>>>>>>>>> believe the benefits outweigh the downsides. > >>>>>>>>>>>> > >>>>>>>>>>>> I would love to hear what others—especially contributors and > >>>> fellow > >>>>>>>>>>>> maintainers—think about this workflow. > >>>>>>>>>>>> > >>>>>>>>>>>> Best regards, > >>>>>>>>>>>> Jarek > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>> --------------------------------------------------------------------- > >>>>>>>>>>>> To unsubscribe, e-mail: [email protected] > >>>>>>>>>>>> For additional commands, e-mail: [email protected] > >>>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>>> > >>>>>>> --------------------------------------------------------------------- > >>>>>>>>>>> To unsubscribe, e-mail: [email protected] > >>>>>>>>>>> For additional commands, e-mail: [email protected] > >>>>>>>>>>> > >>>>>>>>>> > >>>>>>>>> > >>>>>>>>> > >> --------------------------------------------------------------------- > >>>>>>>>> To unsubscribe, e-mail: [email protected] > >>>>>>>>> For additional commands, e-mail: [email protected] > >>>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> > >> --------------------------------------------------------------------- > >>>>>>>> To unsubscribe, e-mail: [email protected] > >>>>>>>> For additional commands, e-mail: [email protected] > >>>>>>>> > >>>>>>>> > >>>>>>> > >>>>>> > >>>> > >>>> > >>>> --------------------------------------------------------------------- > >>>> To unsubscribe, e-mail: [email protected] > >>>> For additional commands, e-mail: [email protected] > >>>> > >>>> > >> > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: [email protected] > >> For additional commands, e-mail: [email protected] > >> > >> > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
