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]
