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] >> >>
