Strategy around increased contributions and AI
So ... we should probably have a discussion about AI :)
This isn't just about AI, but there's definitely a correlation. In short, developer time historically was spent building features, and as things matured, also rearchitecting and fixing bugs. Occasionally, merge requests would come in and some code review would occur. Merge requests would be authored by developers too. There was a line drawn somewhere that users would spend time testing, and coming up with workflows, expressed with text, videos, and mockups.
AI has shifted this line meaning that users could now express themselves directly using code, and even just get on with it and have the feature built without waiting on developers. This has increased the number of merge requests (and direct commits, as we're somewhat lax about commit rights), and therefore also increased the workload on code review. At least for me.
These new contributions range considerably in their nature:
- Generally acupuncturial changes across the codebase by @theoryshaw
- A range of PRs which can and do go up to the thousand of lines mark especially by @falken10vdl (btw, not sure if AI is used here - the point is just that there's a lot more contributions!)
- Also large PRs on the C++ side which seem to have been responded with "No, this is just not right"
- PRs intended for robots by @brunopostle and a multi-thousand line AI-generated interface by agents, for agents
- Entire forks with significant entire new modules and capabilities in the tens of thousands of lines mark, like 4D Bonsai by @Federico_Eraso and Saikei by @myoder89
Good news first! Contributions are GREAT! A huge thank you to everyone! Especially when a main dev goes AWOL for almost a year, things keep on truckin'. And to think we used to talk about the bus factor. Free software always had the caveat of "if you have the technical chops to grok it" but AI seems to be making that history.
This reflects some trends we've probably all seen in the news, where some companies are becoming "AI-first". I.E. that development isn't about code anymore. It's about descriptions.
The current technical reality is that these contributions are rarely ready to go. Bonsai is not a small codebase and the simultaneous concepts of Blender, IFC, and some AEC discipline is a tricky thing to balance (even ignoring programming languages for the moment). This means is a lot of domain knowledge required to design cross-discipline workflows, architectural knowledge required to understand how to structure code, and of course codebase familiarity to know when things can be reused. This is not a low barrier to entry, regardless of whether or not AI is used. Also, when things get merged, if there is a mistake, it's much harder to revert when the merge is many months ago, or if they pile up with consecutive changes. Merged code also presents the additional issue of being hard to distinguish between intentional, designed code in the codebase with legacy "yeah we really should fix that when I find time" code.
What's also clear to me is that AI is only going to get better. Assuming technology and greed doesn't first either kill the entire planet or civilisation, this further abstraction from assembly to CLI to GUI to AI probably means at some point I'm going to :wq Vim for the last time. But right now, the current technical reality is not there yet.
It seems we need more core devs, where a core dev is someone we collectively trust to make architectural, sweeping changes to the code. To do that, we need to promote contributors to core devs. We also need to free up core dev time more, because reviewing multi thousand line PRs is not fast.
So here are my recommendations:
- Make BonsaiPR an official thing. If a PR solves your issue today, let's advertise it (include in official docs), even if the intent is to merge later! If necessary, even BonsaiSuperExperimentalEverythingGoes. Or even entire community forks like 4DBonsai or Saikei. Let's celebrate them.
- Don't merge PRs unless a core dev familiar with that area gives it a thumbs up. Because whilst reviewing PRs is slow, retrospectively fixing something that has already been merged is even slower.
- Merged code needs to be maintainable. To main code, we need to understand code. The developer merging must understand the code. I'm guilty of this in the past of doing James Bond code reviews (merge first, ask questions later).
- Spend more money! Currently, @Andrej730 is financed full time. We have funds for a second, which was meant to be @bruno_perdigao, but from my understanding availability is a bit tricky right now, so we need to figure out if he's available, and if not, who else we can spend money on.
- If we can help agents write better code, let's do so. This might mean an AGENTS.md or something (I don't know this area very well).
- If you have suggestions to improve onboarding devs (better docs?) let's do it. FYI there is a super secret demo tutorial module.
- We need to have a clear instruction on our stance on "AI did everything, wasn't me" regardless of code quality, but in regards to ethics, environment, and legality. The last thing I want is if code grows but suddenly there's a "hey that code is stoken" lawsuit.
- No huge PRs (approx >1k lines for example). Small PRs are faster to process.
- Tests. We really need to get back on top of it. The red crosses in our pipelines are really confusing.
- Clearer priorities. A few attempts were made in the past with kanban boards but things move so fast and we didn't have the discipline to stick to agendas. Increased transparency of dev priorities means less "is he ignoring my PR" moments. I for one will make my own "What is @Moult planning to hack on".
Would really love to hear what everybody thinks and what actions we can do to navigate this new world together.
and 7 others.
Comments
Assuming that we are all ok with AI contributions (there is a valid argument to reject them altogether), I started with a draft AGENTS.md. This is human readable, but its purpose is to give coding agents a baseline for contributions in terms of disclosure, coding style, licensing etc.. what else needs to go into this file?
IMHO I think that probably the strategy should be tailored based on the profiles of the contributors.
As an example, let me share how I am using Ai for Bonsai. In my case, my background is telco troubleshooting (from the time I was writing patches in assembler to recover service in troubled mobile network switches...), not software design... So I was trained and have experience doing hacks (fast) here and there to get things functionaly working. Basically kicking the machine until it works...
That means I am an engineer from tecnicall assistance centers not from design/architecture offices.
So for my background... Ai helps a lot finding pieces of code within the codebase and speeding up answering questions on how blender does things (I guess they are more trained on blender than bonsai). I would then copy a good chunk of base source code from available sources (for example for the copy/paste I would go and grab patch recipes for ExtractElements, in the case it is not from bonsai itself, like the Construction lines I just submitted, I would go and get it from github that has GPL or MIT licensing and would put a note in the code that it comes from that source) and just modify to accomodate the feature I am after. This means that there is not really a well structured design process behind. If I get stuck I would search for alternatives based on my background. For example in the paste part of the clipboard, I had a feeling the crashes are very much related to the API overload, unsafe use of references to IFC/blender objects so try to use AI to "look for alternatives" as to get another base code to start or switch to.
So this means that at least the AI can be leveraged quite differently if you are a core developer, a troubleshooter, an end user, etc.
Regarding @Moult suggestions, I rotally agree with them and I would suggest another one regarding the process to accomodate new contributions. (I do not know if this is rubbish :)) :
Structure the code base in levels of criticality (again this comes from my experience... Typically in telco switches you would that in the actual design of the system, having different priority levels assigned to the code and HW watchdog timer that will tick and force to get your things done under control)? Either explicitly by for example dividing code as "critical" vs "non critical" or just documenting it. This means that the reviewing cycle for contributions can be quite different if it is affecting a critical area of the code vs something that it is not (which could ideally be placed in "extras" settings and "sandboxed" within a dedicated module").
What is your strategy about release numbering of official Bonsai? For me it is really stable and I believe there are people using it in replacement of other commercial ones. Why not at least the one in blender extensions to be date based (2026.03 for example for this years Mrach). Then the unstable version (that already tells you the commit reference) and finally the BonsaiSuperExperimentalEverythingGoes. I think to get user traction the official release should bigger than > 0.x. ;) but that is another topic, sorry.
Just my two cents...
Cheers!
Ps: by the way, I got really fascinated by this project purely random... I am contracting an architect for a second house I am planning in the countryside and I just could not understand I could not see the details myself because the architect's model was in Sketchup/Revit/Autocad and of course it does not make sense for some one like me to get a license for this matter. I searched for alternatives and initially used BIM workbench of Freecad as I already have used Freecad in the past (they moved to 1.x already ;) ). I then found the IFC approach of Bonsai very appealing and that is why I started to make models with Bonsai that I can use to discuss with the Architect. For your info, in the journey I learned about openstudio/energy+ because of an sketchup plugin very much used here in Spain which probably would make for another very usefull PR leveraging gbXML code from @brunopostle :)
Basically i'm totally agree, my two cents on it:
Is this something that could be tailored.
based on the intended audience? I mean if it is human readible I see this could eveolve to help both agents and humans so the effort is shared.
In my dreams I would like to read something like Core Blender Development: Understanding the Essential Source Code for Bonsai ( with hands on info on IFC ) but I agree that requieres a lot of time from core developers. Maybe getting those md files on different topics could be a compromise solution? Core developers spend time in PR Add AGENTS.md contributor guide#7672 so dev info is documented in a manner that serves both audiences?
The AGENTS.md file is sucked in by all bots whenever they are given a coding task, so it literally prefixes any prompt you give them when they start work.
It could certainly be extended with hints about the codebase, such as explaining the whole core / tool / module split in Bonsai (actually this is a good question to ask Claude, what is the purpose of this split?).
@brunopostle I do not know if that could clutter or not the prompting (what is typical size of prompts?) mechanisms. But I think that maybe core developers could get AI to provide some starting point of documentation .md as you suggested above and review those ones to have a base source of truth for this "Understanding the Essential Source Code". For example, in my case I have taken good note of the comments by @Moult and @Andrej730 in the commits and PRs they have reviewed from me. That is very valuable information that could be summarized in those .md files to better understand the architecture, the design choices, etc.
I think we should allow AI written code, but only if it's vetted and supervised. The general rules as for any other code project apply here as well, as outlined by @Moult: small broken up PRs, tests, accompanied by documentation and explanation within the PR.
I have a rather ambivalent view on AI. It's a new tool, but the hype is just exaggerated. This type of new technology has yet to reach its Valley of Disillusionment of the Gardener Hype Cycle.
In its current state AI is promising as a supporting companion but lacks in terms of reliability, stability, reproducibility and mostly correctness. It's a shortcut. But shortcuts are only useful, if you know what you are trading in for the faster way. And it can only produce mediocre results, per design. At least current LLMs do.
Nevertheless, I did what @falken10vdl mentioned in his post and asked ClaudeAI for an overview of the Bonsai code structure based on the Github repo and comments in the PR's and Issues. Here is the result. Looks okayish to me, but I lack deeper knowledge of the project. So I take it with everything an AI produces: a suspiciously big grain of salt.
@falken10vdl I think it could be a bit longer without cluttering things up. @doia seems like a good summary to me, I just learned a couple of things skimming it.
I'm slowly getting back into my routine as a contributor. Currently, I'm refactoring some code related to Snap and Polyline, as they are becoming increasingly integrated with other parts of the code, so I believe this is the right time to tackle it. I also need to enhance testing, which presents challenges in this context, particularly with numerous modal operators that require mouse input. There's quite a bit of essential but less glamorous work ahead.
I mention this because I'm impressed by the new contributions; however, I'm struggling to find a balance between refactoring, bug fixing, writing tests, developing new tools, and reviewing merge requests. Those general recommendations are excellent, and I agree with all of them.
I also want to emphasize that the demo tutorial module is great. Anyone interested in the code should take a look to understand how it is generally organized. This understanding helps when merge requests are made with that organization in mind.
One possible way in order to help core developers to review the PR could be restore the failing tests so the automated github checks in the main branch would all passed and the "check sign" becomes green.
In this way, if a new PR brokes something it would be enlighted by the red check sign.
So one priority now should be to clean and fix all failing test in order to create a trustable starting point.
Here i tried to do that
https://github.com/IfcOpenShell/IfcOpenShell/pull/7701
but it's just a try because i can't fix all failing tests.
I think it is doable with not so much effort.
The topic of these contributions is really transforming quickly these days! If I imagine being in @Moult 's shoes, I picture feeling inundated. But when I zoom out a bit, it presents such an interesting governance question — and a project management question between the two, I suppose. It's like everyone with $20 to spend (and let's be clear: that's not everyone) suddenly has a staff of undertrained, hard-working speed-readers. It's a great problem to have but anyone who has ever done volunteer coordination knows that that is a job that gets a title and a salary because you can't actually use the volunteers at all if you can't dedicate time to supporting how they contribute.
Does OSArch have any connection to the OpenAEC Foundation? I don't know them at all but the recently published this skill package for Claude that I've been mulling over.
If this direction is the new norm, I feel like we do have a lot of opportunity to explore how an open, coordinated system could work. Glad you guys have your heads screwed on straight on the gatekeeping though — I'm strongly in favor of human responsibility on this front.
@Than thanks a lot for the pointer! @FreekHeijting that is an awesome work. I have taken a look to the bonsai skill and I have learned quite some things already I had not realized!
@Moult @Andrej730 @aothms @bruno_perdigao @brunopostle @Massimo @Gorgious @theoryshaw etc. this is like a LoD further down to what @brunopostle started. Please take a look to it. I think it is really nice information that somehow would make sense to link or maintain.
@FreekHeijting I am only using guthubcopilot in vscode to plan and ask things and had built myself an md file of "best practices" based on my interaction with developers that had provided feedback to me in the past.
I have a few questions (sorry if they are obvious) that maybe you can clarify:
Thanks!
For BonsaiPR is possible to get patch list and woting systems for integration so we can push feature for integration to main and Review systems maybe connect with our github account which post Issue claims becouse now in this Pr version we do don’t know what change and which feature is new from original bonsaiBIM and second when MCP integration panel in GUI so we can control agents from BonsaiBim
Here is the specification for agent skills. These are basically a human readable markdown file with a defined YAML front matter section, a 101/how-to/best practices description of a topic, which the clankers can load on demand. Meaning they don't clog the context window up front. They should work with every model, as the format is kind of standardised.
Here is a huge repo with a loooot of community authored skills: https://github.com/sickn33/antigravity-awesome-skills
But DO NOT install them all at once without reading and understanding a skill. It will instruct the model to do things in a specific way and can easily be manipulated. ONLY use a trusted source, install one by one and read it before doing so!
I have a bunch of specific agent skills I use for coding sessions. I store them the in
~/.agents/skills/folder in my home directory. OpenCode and Pi pick them up easily. Claude Code needs a specific location.