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